channels

Every channel this organization has connected. Use when showing what is already connected, or checking before adding another; pass connection_id to ask what answers on one connection (none, or the one channel it carries). Changes nothing.

Connect an account to what answers on it: a flow, or an agent. Use when a new messaging account should start answering through the platform.

Pass flow_id for a flow you drew, or agent_id to have the platform write the one-step flow that hands every message to that agent — one of the two, never both. The flow is editable from the moment it exists. An agent or a flow that is not yours is 404, checked before anything is written.

List the latest subject of each email thread you name: the subject of its newest message that carries one, received or sent. Use to show what each email thread in a list is about now, since one customer may have several email threads open at once. Name each conversation as interaction_id, at most 100. A conversation that is not an email thread, has no subject, or that you may not read is left out. Changes nothing.

End a thread. Use when a conversation on a channel is finished and should close rather than wait indefinitely. The next message from that contact opens a new one, with this one still in the log — and everything that happens when a conversation ends happens now, which on a thread nobody ever closes never happens at all.

Answers 409 while a turn is running on it, and while a person has it. A thread waiting for a person has no holder yet: take it first, and the holder closes it from the inbox. A thread you may not read answers 404, as one that does not exist.

List why each message of a thread was answered, kept for review, acted on, handed to a person or left alone: the outcome the thread flow declared, what it did, the questions its reading steps answered, the flow and the models -- or the platform's rule when no flow ran. Use to show the decision next to the contact's line whose ref_id is message_id. Changes nothing. Answers 404 for a conversation you may not read.

A signed link, good for 15 minutes, to a file the contact sent on this conversation, with its name, type and size. Use when a thread's transcript names a file and you need the file itself; ask again for a fresh link once one expires. The inbox asks when the reader opens the file, not before. view=inline asks for a link that opens the file in place rather than saving it -- honoured for a JPEG, PNG, GIF or WebP image and a PDF; any other file is still a download. Changes nothing. Answers 404 for a conversation you may not read, and for a message whose file is not kept (never kept, refused, or purged).

Give a thread to an agent and take one turn, as a branch of a flow would. Use when a person-held or flow-held thread should be handed to an agent to continue.

The same verb the hand_to_agent built-in runs, over the same code: the agent is attached from this point on, it answers with the thread's transcript in view, and what it said goes back to the contact unless you ask for it not to -- or, on a connection that prepares replies for review, is kept as the thread's prepared reply for a person to send. context is what you know about this contact, shown to the agent as information about who it is talking to and never as words they said. Refused with 409 while the thread is with a person, and with 422 for an agent on a voice profile, which answers calls only. A thread you may not read answers 404, as one that does not exist.

List what an email thread keeps beside each message's words: its subject, whom it was copied to, and its mark (sent automatically, spam, or a sender its domain does not vouch for). Use to show a mail's subject and copies next to the contact's line whose ref_id is message_id. Changes nothing. Answers 404 for a conversation you may not read; empty on a WhatsApp thread.

Read the reply an agent prepared on this thread for a person to review: its text (or template), the agent, the message it answers and whether it is ready or outdated -- the contact wrote again after it. 404 when nothing is prepared. Takes nothing.

Ask the agent for its prepared reply again: the current one is discarded and the agent that wrote it takes one more turn over the messages nobody answered, preparing another -- no other step of the channel's flow runs. Answers the new prepared reply, or null when the agent said nothing. Charged as an agent turn; 402 when the organization's balance is spent, 404 when nothing is prepared, 409 while another person holds the thread.

Discard the reply an agent prepared on this thread, answering what it was. The thread keeps waiting for a person with nothing prepared; writing your own reply then takes it. 404 when nothing is prepared, 409 while another person holds the thread.

Send the reply an agent prepared on this thread, as it is or with text in its place. It goes as yours, marked as prepared by the agent, and the thread goes back to its agent -- unless the agent's own turn handed it to a person, which returned_to_flow says. Sending does not take the thread. An outdated reply is sent only with text (409 without). 409 while another person holds the thread or a turn is running, 404 when nothing is prepared, 402 when the organization's balance is spent. Counted as one message sent without a model.

Answer on a thread yourself: free text, or an approved template. Use when a person, not the flow or an agent, should answer this thread directly.

What you send is on the thread as yours — a third speaker beside the contact and the agent — and replying to a thread nobody holds takes it: from then on its flow is silent and you answer it until you release it. The answer says so: took_thread is true when this reply took the thread, false when you already held it. Refused with 409 while another person holds it (naming them; writing never takes a thread over) or while a turn is running on it, and with 402 when the organization's balance is spent, which takes nothing. Counted as a message sent without a model.

Free text — with choices, if any, as buttons or numbered options — goes only while the road lets the organization speak freely: past the official API's window it is refused with 409 before anything is taken or written, and the body says what would go instead (instead) and when free text stopped (free_text_until). A template goes whatever the window.

attachment sends one file by its public https link, with text as its caption -- free text for the window -- and is on the thread as your line with the link after your words.

One channel: the account it speaks through and the flow that answers. Use when opening a specific channel by id. Changes nothing.

Stop answering on this account. Use when a channel should stop existing entirely, not just stop responding — use update_channel to merely switch it off. Conversations already on it stay in the log; nothing is closed and nothing is refused.

Answers 409 while a turn is still running on one of its threads: that turn finishes, and the same call then succeeds.

Rename a channel, change how long it waits for the next message, or switch it off. Use when a channel's own settings need to change — only the fields given. A channel that is off still records what arrives; it runs nothing.

Write to somebody on this channel who has not written to you. Use when the platform speaks first on a channel, as the organization — a person answering a thread from the inbox replies on the thread instead.

Opens the thread for that address if none is open and reuses the one that is; on an email connection it always starts a new conversation, and so a new thread, under the subject the connection's settings name. What a provider will carry outside its own window is the provider's rule: the official WhatsApp API refuses free text a day after the contact last wrote, and a template is the one message it accepts.

attachment sends one file by its public https link, with text as its caption; the platform never fetches it. A road refuses one larger than it declares for its kind, of a type it does not take, or an audio file with words; choices beside one go as numbered text in its caption.

Sending reads the thread it reaches: an address whose conversation you may not read answers 404, as a channel that does not exist, and nothing is sent.

The channel's open conversations you may read — whose address, and which record. Use when showing a channel's live threads, before closing or handing one to an agent. Changes nothing. What was said on one is read from the interaction log like any other conversation.

The people the organization vouches for. Use when showing the roster, or checking for an existing entry before creating another. Changes nothing. Owners and admins read every entry; a member reads their own.

Vouch for somebody with no account: a name and the addresses they write from. Use when a person without a platform account should still be recognized by their addresses. Owners and admins only.

Your own entry: the one linked to your membership, whatever your role. Use when the caller needs their own roster entry rather than a named one. Changes nothing. 404 when your membership has none.

One entry: any for an owner or an admin, your own for a member. Use when opening a specific roster entry by id. Changes nothing.

Stop vouching for somebody with no account. Use when a roster entry should no longer exist. An entry that is a membership's leaves when the membership ends, and is refused here.

Rename an entry. Use when a roster entry's name needs correcting. Owners and admins only.

Add an address an entry writes from. Use when a roster entry starts writing from a new address. 409 when it is already on the roster.

Change one of an entry's addresses. Use when an address on file is wrong and should be corrected in place. 409 when the new address is already on the roster.

Remove one of an entry's addresses. Use when an address should no longer be recognized as this entry's. An entry with no account is known only by its addresses and keeps one: removing its last is refused — remove the entry instead.