Skip to main content
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:
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.