Skip to main content
Comms has a small set of concepts. Understanding them once makes every API page obvious.

​
Line

A line is the phone identity customers text — SMS and iMessage on the same number where available. Outbound API sends leave from that line. Inbound replies land on that line and show up in the inbox and Messages API.

​
Messages API key

A Messages API key authenticates your server to Comms. Keys are minted under Messages API in the dashboard. Default scopes are send + read.

​
Conversation

A conversation is a thread between your line and a customer (usually keyed by their phone). You can:
  • Start one by sending to a new to number.
  • Continue one by passing conversation_id on send.
  • List them via GET /api/v1/comms/conversations.

​
Contact

A contact is a person you message — phone, optional name, email, tags. Listing is read-scoped; upsert currently expects a broader write scope when present on the key.

​
Agent (optional)

An agent is the no-code path: instructions, knowledge, tools, and handoff rules running on the line. You do not need an agent to use the Messages API. Many teams use both:
  • API for system-triggered texts (receipts, status, ops).
  • Agent for free-form customer replies.
  • Humans for handoff in the inbox.

​
Delivery

When you POST a message, Comms accepts it (202), places it on the line, and tracks delivery attempts. Inspect attempts with events when something looks stuck.

​
Mental model