Channels API

List channels

Lists the workspace's channels (phone numbers, WhatsApp numbers, Instagram and Messenger pages, website widgets, iMessage lines), newest first.

A WhatsApp sync channel reads status: "unknown" (and health: "warning") while its sync service is not reporting, because its last known state cannot be trusted then; status_detail gives the reason (bridge_offline or no_heartbeat) and since, the last time it reported. It is null for every other channel.

The status filter matches the current status, so a channel that reads unknown is left out of it.

A phone (voice) channel also has language, the language it speaks, voice, the voice it speaks with (id and name; change it with PUT /v1/channels/:id/voice), receives_calls, whether calls to its number ring it now (inbound_enabled is only the channel's own switch), and incoming_calls_number, the number whose calls ring it now: its own, or an earlier number still routed to it (null when none does). They are null on other channels, and the last two on a Zoom Phone channel, whose lines are set on its Zoom page. phone_number_id is its number's id, and scheduling_mode the scheduling system set on any channel (null when none was set; PUT /v1/channels/:id/scheduling).

Get a channel

Returns one channel with its call settings (voicemail, retries, callbacks, evaluation sampling) and the agents on it.

A WhatsApp sync channel reads status: "unknown" (and health: "warning") while its sync service is not reporting, because its last known state cannot be trusted then; status_detail gives the reason (bridge_offline or no_heartbeat) and since, the last time it reported. It is null for every other channel.

A phone (voice) channel also has language, the language it speaks, voice, the voice it speaks with (id and name; change it with PUT /v1/channels/:id/voice), receives_calls, whether calls to its number ring it now (inbound_enabled is only the channel's own switch), and incoming_calls_number, the number whose calls ring it now: its own, or an earlier number still routed to it (null when none does). They are null on other channels, and the last two on a Zoom Phone channel, whose lines are set on its Zoom page. phone_number_id is its number's id, and scheduling_mode the scheduling system set on any channel (null when none was set; PUT /v1/channels/:id/scheduling).

Phone (voice) channels are created with POST /v1/channels on a number the workspace has. Connecting WhatsApp, Instagram, Messenger, Apple Messages or Zoom and installing the website widget need a person (a Meta or Zoom login, a device), so those channels are created in the dashboard.

Create a phone channel

Puts an agent on one of the workspace's numbers with a voice of the list, as the dashboard's new phone channel does: the agent calls from the number and answers its incoming calls. The channel runs on the workspace's NuTalk call line and counts toward the plan's channels. Only type: "voice" is created here: WhatsApp, Instagram, Messenger, Apple Messages, the website widget and Zoom are connected in the dashboard, and numbers are bought or verified there.

This puts an agent in front of real callers: calls to the number reach it as soon as the channel exists. Confirm with the user first.

The channel is created whole or not at all: when the number can't be put on it, the new channel is deleted again.

Creating never waits for approval, except with confirm_move_from_channel_id: taking another channel's incoming calls is a change, so it waits for an owner's or admin's approval when the key's changes do, as the same move through PUT /v1/channels/{id}/incoming-calls does.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Change a channel's number

Gives a phone channel another of the workspace's numbers, as the channel page's number picker does: the agent calls from it from now on. Where the number's incoming calls ring changes only when you say so: receive_calls: true routes them to this channel, false takes them off it, and without it they stay where they ring (an earlier number still routed here keeps ringing the channel).

With receive_calls: true, callers of the number reach the agent at once: confirm with the user first.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Turn a channel's incoming calls on or off

The channel page's incoming-calls switch: receive_calls: true makes calls to the channel's number ring it, and its agent answers them; false stops them (the call is rejected: callers hear busy). A number whose calls ring another of your channels moves here only with confirm_move_from_channel_id, and that channel stops receiving them.

Turning calls on puts the agent in front of real callers: confirm with the user first. Turning them off is a stop, so it never waits for approval.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Change a channel's voice

Changes how a phone channel speaks: its voice (one of GET /v1/voices), its language and the voice's settings, as the channel's Voice editor saves them. Everything else stays as the channel has it. A newly picked voice starts with the settings its demo was recorded with (speed 1, stability 0.5, similarity 0.75), unless voice_settings says otherwise; a channel keeps a voice it already has even when it left the list.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

List the voices

The voices a phone channel can speak with: the same list every voice picker in the dashboard offers, featured ones first, with a recording of each. Regina (default: true) is the one a new channel starts with when neither the request nor its agent picks another.

Delete a channel

Deletes a channel of any type, as the dashboard does. A phone channel's number stops ringing it and becomes free for another channel, and campaigns that called from it lose their number. A WhatsApp, Instagram or Messenger channel stops receiving messages: NuTalk unsubscribes from its account's webhooks at Meta. A website widget or Live Room stops answering visitors, and an Apple Messages channel's Mac is unlinked. Its conversations and their messages are permanently deleted: delete_message_history: true (in the body or the query string) confirms that. The Zoom channel is deleted on its own page in the dashboard, which retires its lines.

Nothing brings the channel or its history back: confirm with the user first.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Update a channel

Changes the settings you send: the channel's name, its automatic evaluation (on or off, the share of finished conversations evaluated, and on messaging channels how long a silence ends a conversation) and, on a phone channel, whether it refuses callers with a hidden or unknown number. Numbers, connections and the widget's look are set in the dashboard.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Put an agent on a channel

Makes the agent the one that answers on the channel, with its deployed version, as the dashboard's channel picker does: any other agent on the channel is taken off it (a website widget's chat and calls both go to this agent), and later deploys of the agent move the channel to the new version. The agent must be deployed and not archived.

Customers reach the agent at once: on a messaging channel, whether the AI answers them also depends on the channel's AI mode (PUT /v1/channels/:id/ai-mode).

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Take the agent off a channel

Takes an agent off the channel, as the agent page's unlink does: everything that makes it answer there goes (the channel's binding to its version, its widget roles, the assignment), and nothing of another agent's. The channel stays connected, with its settings, and has no agent until one is put on it. Name the agent with agent_id (in the body or the query string); without it, the channel's only agent is taken off.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Switch who answers a channel

Switches who answers a messaging channel's chats (WhatsApp, Instagram, Messenger, website widget, Apple Messages): off, the team answers (the AI only answers the chats a person let it answer); testing, the AI answers only the channel's test numbers (phone-number channels); live, the AI answers new conversations, and with live_scope: all existing chats too from their next message; paused, the emergency stop; resume, the AI back on exactly as it was before the pause. It goes through the dashboard's one switch, under the channel's lock, and is recorded in the channel's activity.

This puts the AI in front of real customers (or takes it away): switch with the same care as in the dashboard. Only owners and admins switch it: the key's creator must be one of them.

Set a channel's scheduling system

Sets the only scheduling system the agent on the channel may book with: calcom, business (Business appointments), clinic, restaurant, or none to turn booking off on this channel. A system can be chosen only when the workspace has it (its module, or a connected Cal.com), and an agent books one way only: when its booking method was chosen, the channel takes that method or none.

The change runs the dashboard's channel rules as the member who created the key: the key needs channels:write and that member a role that changes channels (owner, admin or builder). A key whose creator has left the workspace, and a reseller key, are refused.

Create a website widget

Creates a website widget channel, as Channels → Website widget does: an agent that chats and one that takes calls (each with a deployed version; the call agent defaults to the chat agent), the modes the workspace has, the websites it runs on, its greeting and its look. The answer carries embed_key, which the website's snippet uses; it is public by design.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Once its snippet is on a website, the agent answers its visitors.

Get a website widget's settings

The website widget's agents, modes, the websites it runs on, greeting, consent notice, look, the visitor details it asks for and its embed key.

Change a website widget

Changes the settings sent; the rest stay as saved (the websites it runs on are never cleared by a request that leaves them out). A mode switched on must be one the workspace has; one already on stays. capture_fields sets the visitor details it asks for and whether it asks before they start.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Get a messaging channel's settings

For a WhatsApp, Instagram, Messenger or Apple Messages channel: who gets its chats when the AI hands them over (default_operator_id, a teammate), WhatsApp's human-like timing and grouping of quick messages in a row, and whether a team message from outside NuTalk holds the chat (team_first_message_holds: the first message on Apple Messages, Instagram and Messenger, a reply from the phone or WhatsApp Web on a WhatsApp QR line). A setting the channel doesn't take is null. The AI mode is GET /v1/channels/{id}.

Change a messaging channel's settings

Changes the settings sent; the rest stay as saved, and never the channel's transport or its AI mode (PUT /v1/channels/{id}/ai-mode). A setting the channel doesn't take is refused. Setting an Instagram or Messenger channel's default operator also assigns them every chat nobody has, so it needs conversations:write too.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Get a phone channel's menu navigation

Whether the agent presses keys through phone menus on the channel's outbound calls, what it aims for there (goal, e.g. reach the billing department) and the keys it already knows (known_sequence).

Change a phone channel's menu navigation

Changes the settings sent; the rest stay as saved. It applies to the channel's next outbound calls.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

List a channel's test numbers

The numbers the AI answers while the channel is in Testing (AI mode testing), with the AI's last reply to each and whether it remembers earlier messages. WhatsApp and Apple Messages channels.

Add a test number

Adds a number the AI answers while the channel is in Testing, from the next message it sends; that phone's existing chat is answered too. At most 10 per channel. Answers the channel's test numbers. Only add your team's own phones.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Remove a test number

The AI stops answering the number while the channel is in Testing. A stop, so it never waits for an owner's approval.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Start the AI over with a test number

The test number's next message is answered as if it were the first: the AI forgets the earlier messages (messages), what it remembers about the person (memory), or both. Nothing is deleted. It starts the person over, as Start over does in the dashboard: every chat of that phone in the workspace, on any channel, not only this channel's.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

Create a Live Room

Creates a Live Room, as Channels → Live Room does: a page at its own link where visitors talk with the agent and the page shows what they need as they talk. It starts from a template's questions and screens and the workspace's brand, with the agent that answers (it needs a deployed version) and books the way that agent books. Answers the room as GET /v1/channels/{id}/live-room does, with its url and its embed_key (public by design: a website's snippet carries it).

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

It answers visitors as soon as it is created: share its link, or embed it on a website.

Get a Live Room's settings

The Live Room's link and embed key, the agent that answers, whether visitors can talk now, the questions it asks, what it may show on screen, its look, the websites that embed it, the longest call and the recording notice. The agent is changed with PUT /v1/channels/{id}/agent.

Change a Live Room

Changes the settings sent; the rest stay as saved. questions replaces the whole list; on_screen, look, consent and the texts change only what they name. accepting_calls: false stops new calls at once and never waits for approval.

A change runs the dashboard's own rules as the member who created the key, keeping every setting the request leaves out as saved. A key whose creator has left the workspace, and a reseller key, are refused.

List a channel's testers

Who the AI answers while the channel is in Testing (AI mode testing): a WhatsApp or Apple Messages channel's test numbers (kind phone), or the people who are a Messenger or Instagram channel's testers (kind messenger or instagram, with their name and chat), and how each was added (added_via: number, chat or code). With the AI's last reply to each and whether it remembers earlier messages.

Add a tester from a chat

Makes the person of one of a Messenger or Instagram channel's chats a tester: while the channel is in Testing the AI answers them from their next message. At most 10 per channel. Find the chat with GET /v1/conversations?channel_id=…. Answers the channel's testers. Only add your team's own people.

A change runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.

Remove a tester

The AI stops answering the tester (a test number or a person) while the channel is in Testing; their chat goes back to your team. A stop, so it never waits for an owner's approval.

A change runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.

Start the AI over with a tester

The tester's next message is answered as if it were the first: the AI forgets the earlier messages (messages), what it remembers about the person (memory), or both. Nothing is deleted. A test number starts over as a person, in every chat of that phone in the workspace; a Messenger or Instagram tester in their chat on this channel.

A change runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.

Make a tester code

Makes a tester code for a Messenger or Instagram channel, as "Add me with a code" does: for 15 minutes, whoever sends it as a message to the Page or account (link opens that chat) becomes a tester, up to the channel's 10, and NuTalk answers them "You're a tester". The code is answered only here, once: NuTalk keeps its sha256, never the code. Share it with your team only. GET /v1/channels/{id}/ai-testers then lists who it added (their code_id).

A change runs the dashboard's own rules as the member who created the key. A key whose creator has left the workspace, and a reseller key, are refused.

List a WhatsApp number's templates

The templates of the number's WhatsApp account, each language on its own, from the copy NuTalk keeps (Meta's updates keep it current; synced_at says when NuTalk last read the whole account). fields lists what a sender gives when sending one, with what NuTalk fills each from (source, set with PATCH …/fields). Send an approved one with POST /v1/conversations/{id}/messages. Deleted templates only with status=DELETED.

Read as the member who created the key (any role that sees the workspace). A reseller key is refused.

Create a WhatsApp template

Sends a new template to Meta for review, as Manage Templates does. It belongs to the number's WhatsApp account (every channel of that account sees it) and is PENDING until Meta decides. Name it with lowercase letters, digits and _; give examples of its fields.

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Get a WhatsApp template

One template of the number's WhatsApp account, every language of it, from NuTalk's copy.

Read as the member who created the key (any role that sees the workspace). A reseller key is refused.

Delete a WhatsApp template

Deletes the template from the number's WhatsApp account at Meta: every language of it, or only the one language names. It is gone for every channel and campaign of that account, and a campaign step that sends it stops working.

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Restore an archived WhatsApp template

Restores one archived language of a template: WhatsApp archives a template unused for 12 months, and restoring it brings back the status it had. Its status reads UNKNOWN until NuTalk's next read of the account says which.

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Set what fills a WhatsApp template's fields

Saves what fills each field of one language of a template when someone sends it, as the Templates tab does: the contact's data, one of the workspace's contact fields, the contact's next appointment, the business's name, or typed by the sender. field_sources is keyed by the field's source_key (GET lists it: first_name, 1, header.1) and replaces the language's sources. It stays in NuTalk: WhatsApp never sees it, so it needs no review.

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Get a WhatsApp number's business profile

The business profile customers see on the number (about, description, category, address, email, websites, photo) as WhatsApp last answered it, asked again when older than five minutes, with its name and blue check. two_step_pin says whether NuTalk keeps the number's two-step PIN, never the PIN; refusal says why WhatsApp's last ask got no answer.

Read as the member who created the key (any role that sees the workspace). A reseller key is refused.

Change a WhatsApp number's business profile

Changes the fields sent on WhatsApp, as the Profile tab does: only those go to WhatsApp, the others stay as they are there. Customers see the change at once. NuTalk checks WhatsApp's limits first; when WhatsApp still refuses, nothing changes and its own words come back with the field they name. The name, the photo and the blue check stay in the dashboard (the channel's Profile tab).

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Try a held WhatsApp account's templates again

"I added a card": when Meta refused a template for payment, NuTalk holds the account's templates (a send answers whatsapp_payment_hold) and pauses the campaigns that send them. After you add a payment method in Meta, this sends the account's next template to Meta as a try and starts the paused campaigns again so one of theirs can be it. Meta's answer to the try ends the hold, or keeps it. The campaigns it starts again send to customers, so it needs campaigns:write as well.

It runs the dashboard's own rules as the member who created the key: templates and the business profile belong to the WhatsApp account, so that member must be an owner or admin. A key whose creator has left the workspace, and a reseller key, are refused.

Meta charges the try, and the campaigns that start again send to customers: confirm with the user first.