> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Communications API
> Read inbox conversations, recordings and transcripts, manage channel suppressions, and render content templates through the Goliath developer API
## About
Read the key owner's inbox, full text and email threads, call recordings and
meeting transcripts; suppress a phone number or email address 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](/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 the text-thread ids and phone lines visible for one contact, without message bodies. Use it to disambiguate before reading a thread. |
| `getTextThreadMessages` | Page one text conversation's full message bodies (max 100), newest first by default. An empty list can mean the thread is absent or outside the key owner's phone visibility. |
| `getEmailThread` | Read every message in one email thread, oldest first, including plain-text bodies when available and attachment names. Email remains user-owned: a teammate's mailbox returns an empty list 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 previews**
`listInboxThreads` 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.
**Page the whole meeting before concluding**
A 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.
### 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 guard**
An 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 mailboxes**
`listCommunicationChannels` 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](/developer-api/account) for
the settings links to hand a user.
**Creating and editing templates**
This API only *renders* content templates. Creating, updating, and deleting
templates lives in the
[Content Templates / Workflows API](/developer-api/content-templates).
## 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:
```bash theme={null}
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](/developer-api/overview#discovering-operations).