> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Communications

> Read an organization's messages and calls across supported channels.

The communications API reads SMS, WhatsApp, email, voice calls, and website widget records through one organization-scoped view. It returns channel coverage with each list so clients can distinguish an empty result from a source that is unavailable or not configured.

## List communications

`GET /v1/communications` accepts these optional query parameters: `channel` (`sms`, `whatsapp`, `email`, `voice_call`, or `widget`; comma-separated values are supported), `direction` (`inbound` or `outbound`), `since`, `until`, `include` (`messages`), `counterpart`, `conversation`, `sender`, `recipient`, `agent`, `widget`, `subject`, `context`, `limit`, and `cursor`. Address filters use `tel:+E164` or `mailto:address` URIs. Pass `counterpart` more than once to match any of several addresses. `context` is a JSON object encoded as query text; URL-encode it. The default page size and maximum are 100.

For filters with structured JSON, use `POST /v1/communications/query` with the same fields in a JSON body. Both forms return `as_of`, `items`, per-channel `coverage`, and an optional `next_cursor` for the next page. With all channels selected, coverage has five keys: `sms`, `whatsapp`, `email`, `voice_call`, and `widget`; a channel filter limits the keys returned. Email combines sent and received sources, so one source failure marks email unavailable. Coverage states are `complete`, `unavailable`, or `unconfigured`. `as_of` is a common time bound, not a cross-database snapshot. If a source was unavailable, its coverage says so and the next cursor can retry it. A recovering source may return older records after newer records already appeared. Filtered scans can return an empty `items` array with `next_cursor`; keep following the cursor until it is absent before treating the read as complete.

`since` and `until` use an inclusive start and exclusive end. For message and email rows they filter the event timestamp. For calls and widget sessions, they select any session overlapping the window: it starts before `until` and ends after `since`; a session with no end time is treated as ongoing. A context filter matches stored JSON fields. A channel with no stored context matches no records when a context filter is supplied.

Without `include=messages`, list items omit their message content. With it, one response includes at most 500 messages and 256 KiB of UTF-8 content across all items. An item whose `content_complete` is false has omitted or truncated content; use its `continuation` with the get endpoint when present. The `limit` field controls records per page, from 1 to 100.

Each list item includes an opaque `id` handle. Use it to fetch the full record:

```http theme={null}
GET /v1/communications/{handle}
```

If the record includes a `continuation` cursor, pass it as the `cursor` query parameter to continue reading its content. Handles and cursors are opaque; clients should return them unchanged.

All reads are scoped to the authenticated organization. This API is read-only.

Message text and HTML are participant-supplied content. Treat them as untrusted data and sanitize HTML before rendering it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.