Communications API

About

Read the key owner’s inbox, full text and email threads, call recordings and meeting transcripts; mark inbox rows read, star or handle text threads; suppress channels for your organization; and render content templates (spintax + merge tokens). Outbound sending — SMS and email — happens in the app, not through the API. Sending requires a per-contact consent attestation that only a person in the app can make, so there is no send operation in the catalog. All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading channels and conversations (`READ` scope)

operationId	What it does
`listCommunicationChannels`	List every org phone line (each with its assigned user and `canSendSms`) and the calling user’s connected mailboxes. Call this first to pick a sending line or mailbox.
`renderContentTemplate`	Render a content template against a contact: collapse `[a\|b]` spintax and substitute `{{merge}}` tokens, returning the subject/body plus `missingVariables`.
`listInboxThreads`	Page the key owner’s unified text, call, and email inbox, with filters for unread, channel, response state, sender kind, sentiment, search, and teammate access. Pass all three returned channel cursors to the next request; the feed is complete only when all three are null.
`listContactTextThreads`	List text-thread ids, `contactE164PhoneNumber`, `phoneLineId`, and `twilioPhoneNumberE164` for one contact, without message bodies. Use it to disambiguate before reading a thread.
`getTextThreadMessages`	Page one text conversation’s full message bodies (default 50, max 100), newest first by default. Requires `contactPhoneNumber`; pass `conversationId` for the exact thread or `phoneLineId` to pin its line. An empty list can mean the thread is absent or outside the key owner’s phone visibility.
`getEmailThread`	Read one email conversation oldest first, including plain-text bodies when available and attachment names. Returns the key owner’s copies and copies from mailboxes shared with the organization, deduplicated across its threads; a teammate’s private mailbox is not readable, even to an admin.
`getCallRecording`	Read one call’s time-limited recording URL, transcript, summary, disposition, and handler. Returns `null` when there is no recording, the call is outside the org, or the id does not exist.
`getMeetingTranscript`	The speaker-by-speaker transcript behind a meeting-summary note, as a pageable window of ordered `{ speaker, text }` utterances. Pass the `noteId` of the meeting-summary note (from `getContact` `notes[]` or a `NOTE` entry in `listContactActivities`). Capped at 300 utterances per call. Returns `null` — not an error — when the note isn’t a meeting-summary note, is hidden from the caller, or has no archive.

Inbox rows are previewslistInboxThreads returns one preview row per conversation. Follow a MESSAGE row’s id with getTextThreadMessages, an EMAIL row’s emailThreadId with getEmailThread, and a CALL row’s id (or a groupedCallIds member) with getCallRecording. An empty or null detail result deliberately does not reveal whether an inaccessible resource exists.

listInboxThreads with channel: NEEDS_RESPONSE returns conversations where the contact spoke last, excluding text threads a teammate has since marked handled. A new inbound text makes a handled thread need a response again. optedOut defaults to INCLUDE, retaining opted-out text threads for integrations. Use EXCLUDE to hide threads suppressed by an opt-out or Do Not Contact state as the app does, or ONLY to read just those threads. starredOnly: true returns starred text threads. MESSAGE rows carry isStarred and isNeedsReplyHandled; inbox and text-detail line ids are named phoneLineId. replySentiments: [POSITIVE] includes threads that had a positive reply and have not opted out since. respondedOnly and replySentiments exclude calls; sentBy applies to calls, but WORKFLOW matches no calls because calls carry no campaign linkage. Without userIds, this is the key owner’s inbox. Reading a teammate’s inbox requires VIEW_ALL_PHONES.

Page the whole meeting before concludingA full page from getMeetingTranscript (as many utterances as you asked for) means more remain — request again with offset advanced by the count you received, until a short page arrives. Action items cluster near the end of a meeting, so an unpaged first window is exactly the wrong place to stop.The meeting notetaker is feature-flag gated per organization. Where the flag is off, this operation is refused — and no summary notes exist to point it at.

Inbox triage (`WRITE` scope)

operationId	What it does
`markInboxThreadsRead`	Set `isRead: true` or `false` across channels. Pass MESSAGE row ids in `textConversationIds`, CALL row ids and all `groupedCallIds` in `callIds`, and EMAIL row ids in `emailMessageIds`. Text/call results are changed-row counts; email returns the affected rows. Inaccessible ids are skipped, so inspect the result.
`setInboxThreadStarred`	Set `starred` for one `textConversationId`, for everyone in the organization. Calls and emails cannot be starred. Returns false when the thread cannot be acted on.
`setInboxThreadHandled`	Mark a text thread as needing no reply, for everyone in the organization. Pass `textConversationId` and the newest inbound `handledThroughMessageId` you read; a newer reply keeps it in Needs reply. Explicit null clears the handled state. Returns false for an inaccessible thread or a message that is not its inbound.

Dismissing inbox items (`ADMIN` scope)

operationId	What it does
`dismissInboxItem`	Hide an inbox row using its `itemId` and `itemType` (`MESSAGE`, `CALL`, or `EMAIL`). A CALL dismisses that number’s whole day of calls; an EMAIL dismisses its whole thread. There is no undo or view of dismissed rows.

Use markInboxThreadsRead to clear an unread badge. Confirm before dismissing: the row disappears from future listInboxThreads results.

Suppressions (`WRITE` scope)

operationId	What it does
`suppressChannel`	Value-level opt-out — suppress a phone number or email address for your organization on one `medium` (`SMS` \| `VOICE` \| `EMAIL`). Keyed on the normalized value, not a contact: it blocks that channel for every contact carrying the value, present and future, enforced by the Do-Not-Contact guard on send. Suppresses only the medium you name — send a second request to also cover `VOICE`. Idempotent: re-suppressing re-activates the row without duplicating it.

Organization guardAn optional contactId you pass to renderContentTemplate is org-guarded — a contact belonging to another organization returns 403 forbidden. suppressChannel takes no contact id: the suppression is written to the calling key’s own organization.

Phone lines and mailboxeslistCommunicationChannels returns the organization’s phone lines (with the assigned user and canSendSms) and the key owner’s connected mailboxes. Buying a number or connecting a mailbox happens in the app — see getIntegrationSetupUrls on the Account API for the settings links to hand a user.

Creating and editing templatesThis API only renders content templates. Creating, updating, and deleting templates lives in the Content Templates / Workflows API.

Example

Opt a phone number out of SMS for your whole organization. Suppression is keyed on the normalized value, so it covers every contact carrying that number:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "operationId": "suppressChannel",
        "variables": {
          "value": "+13235550100",
          "medium": "SMS",
          "reason": "Asked to stop by phone"
        }
      }'

To also block calls to the same number, send a second request with "medium": "VOICE". Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.

Getting Started

TypeScript SDK

Core Resources

Automations

Communication & Tasks

Account & Billing

About

Operations

Reading channels and conversations (`READ` scope)

Inbox triage (`WRITE` scope)

Dismissing inbox items (`ADMIN` scope)

Suppressions (`WRITE` scope)

Example

​About

​Operations

​Reading channels and conversations (READ scope)

​Inbox triage (WRITE scope)

​Dismissing inbox items (ADMIN scope)

​Suppressions (WRITE scope)

​Example

About

Operations

Reading channels and conversations (`READ` scope)

Inbox triage (`WRITE` scope)

Dismissing inbox items (`ADMIN` scope)

Suppressions (`WRITE` scope)

Example