Skip to main content

Telephony blueprint

A blueprint is a contract an app implements so that neither side writes custom code: the app sends the contract's events, and KudosCRM maps each one to the right records — call activities, SMS and voicemail, follow-up tasks for missed calls, owners matched from agents. The first one is the telephony contract, telephony_v1, for calling and SMS apps.

info

The contract itself — every event, what it writes, the fields, the rules and what "ready to list" means — is canonical in the app: /developers/blueprints/telephony. That page reads the same data the server enforces (GET /api/v1/public/blueprints/telephony), so it is never out of date. This page only says how the pieces fit.

In short​

  • Scopes. A telephony app requires contacts:read, users:read, activities:write and tasks:write, and may ask for leads:write (optional — it lets unknown callers become leads). The scope catalog is at /developers/scopes.
  • Events in. Four are required — call.started, call.answered, call.missed, call.logged — and the rest are sent when your product supports them: contact.match, voicemail, SMS and MMS, recordings, transcripts, summaries, sentiment, tags and notes, contact.updated and contact.deleted.
  • Where they go. POST each event to the install's own ingest_url (from the token response), signed with the install's derived key, with install_id in the body. The envelope, the signature and every refusal are in the API reference under Ingest; the signature scheme is the one in Webhook signing, with the derived key as the secret (see App webhooks for how it is derived).
  • The rules. Each event is applied once (resend freely); order does not matter — the opening events open the call whichever arrives first, and an update for a call KudosCRM has not seen yet is held and retried for up to 24 hours; people are never overwritten; back off when told.
  • Agents. Upload your agents with PUT /api/v1/app/agents; KudosCRM matches each to a workspace member by email, and the admin matches the rest during setup. A call's owner is the matched agent, else the fallback owner the admin chose.
  • Events out. KudosCRM sends your app the events your manifest lists — a calling app usually asks for contact.created and contact.updated, to keep caller ID current. They are in the outbound catalog at /developers/events.
Build an app

Register the app, install it with OAuth, and get it listed.

App webhooks

Verify the events KudosCRM sends your app.