To let an assistant use these tools, grant AI agents on the consent screen, or just
Channels under its Fine-tune. The scope is channels.
Read tools work with Read only or Read & write access; write tools only with
Read & write.
Your assistant doesn't see these tools straight away. It finds them with search_tools or
describe_tools, and runs one with use_tool, passing its name and
arguments. Most assistants do this for you: just ask for what you want.
What your assistant is told about this group
Where your agents talk to customers. Each agent is set up on channels (web chat, SMS, WhatsApp, email, form guide, voice), each with its own settings, such as its phone number and its default journey: the question flow the agent takes customers through on that channel (with none set, it doesn't take them through one). Also here: templates for outgoing messages, email templates (the HTML layout around each email), the domains email is sent from, and your WhatsApp setup (your own templates, which one each automatic message uses, and connecting a WhatsApp number). Turning a channel on or off, or disconnecting WhatsApp, changes whether customers can reach you: confirm with the user first.
The descriptions below are the ones your assistant reads, so they're written for it. When a connection covers more than one
organisation, the assistant passes org (the organisation's slug, from list_orgs) to say which one.
list_channel_deployments
Read List an agent's channels
One agent's channel deployments (web/sms/whatsapp/email/form_guide/voice); channels without a row are simply not yet configured.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_inbound_email_drops
Read List emails an agent didn't get
Emails to an agent's email channel that were set aside instead of answered, newest first, with the reason: automatic replies, bounces, bulk or mailing-list mail, Subcontext's own notifications, and mail providers' forwarding confirmations (with their code and link). Use it to explain why the agent didn't reply to an email.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| limit | integer | How many, newest first (default 20, at most 50). |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_channels_overview
Read Channels overview
Every channel deployment across the org, grouped by channel type.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_channel_deployment
Write Configure a channel
Set an agent's settings on one channel (forwarding email, email template, voice, default journey and so on). The first time, this sets the channel up. default_journey is the question flow the agent takes customers through on this channel; with none set, it doesn't take them through one. crm_campaign_id is the campaign (list_crm_campaigns) a new lead who comes in on this channel joins, when no lead form, quote form or utm_campaign names one; an empty string clears it.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| channel_type required | string |
One of: "web", "sms", "whatsapp", "email", "form_guide", "voice"
|
| enabled | boolean | |
| forwarding_email | string | |
| email_template_key | string | |
| email_template_id | string | |
| voice_id | string | |
| default_journey | string | |
| crm_campaign_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
toggle_channel_deployment
Write Enable/disable a channel
Flip a channel on or off for an agent: a live channel change. Confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| channel_type required | string |
One of: "web", "sms", "whatsapp", "email", "form_guide", "voice"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
attach_channel_number
Write Attach a phone number
Bind a pool Twilio number to a channel deployment (must support the channel and be available to this org).
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| channel_type required | string |
One of: "web", "sms", "whatsapp", "email", "form_guide", "voice"
|
| twilio_phone_number_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
detach_channel_number
Write Detach a phone number
Release the deployment's number back to the pool (sibling channels keep it).
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| channel_type required | string |
One of: "web", "sms", "whatsapp", "email", "form_guide", "voice"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_message_templates
Read List message templates
Custom outbound message templates plus the built-in registry starters.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_message_template
Read Get a message template
One custom message template.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_message_template
Write Create a message template
Create a custom outbound message template ({{placeholders}} supported).
Arguments
| Field | Type | Description |
|---|---|---|
| name required | string | |
| body required | string | |
| channels | array of string | |
| email_subject | string | |
| email_template_key | string | |
| email_template_id | string | |
| category | string | |
| purpose | string |
service (default), or first_party_marketing: every send of it then needs the person's marketing consent.
One of: "service", "first_party_marketing"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_message_template
Write Update a message template
Edit a custom message template. Only the fields you pass change.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| name | string | |
| body | string | |
| channels | array of string | |
| email_subject | string | |
| email_template_key | string | |
| email_template_id | string | |
| category | string | |
| purpose | string |
service (default), or first_party_marketing: every send of it then needs the person's marketing consent.
One of: "service", "first_party_marketing"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_message_template
Write Delete a message template
Delete a custom message template.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_email_templates
Read List email templates
Your custom email templates (the HTML layout around each email) and the built-in ones.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_email_template
Read Get an email template
One custom email template with its HTML.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_email_template
Write Create an email template
Create a custom email template: the HTML layout around each email. It must include the body placeholder.
Arguments
| Field | Type | Description |
|---|---|---|
| name required | string | |
| html_content required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_email_template
Write Update an email template
Edit a custom email template.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| name | string | |
| html_content | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_email_template
Write Delete an email template
Delete a custom email template.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
generate_email_template
Write Draft an email template with AI
Starts the AI drafting email template HTML from a description (optionally revising current_html). It takes a few seconds: poll get_email_template_generation with the id, then save the html with create_email_template or update_email_template. Manager or owner.
Arguments
| Field | Type | Description |
|---|---|---|
| prompt required | string | |
| current_html | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_template_versions
Read List a template's versions
Every saved version of a custom message or email template, newest first. Works for a deleted template too: a sent message's template_refs name the id and version it was built from.
Arguments
| Field | Type | Description |
|---|---|---|
| template required | string |
message (a message template) or email (an email design)
One of: "message", "email"
|
| id required | string | The template's id |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_template_version
Read Get a template version
One saved version of a custom message or email template, with its content exactly as it stood: what a message that recorded this version was built from.
Arguments
| Field | Type | Description |
|---|---|---|
| template required | string |
message (a message template) or email (an email design)
One of: "message", "email"
|
| id required | string | The template's id |
| version required | integer | The version number |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_email_template_generation
Read Get an AI email template draft
The status of generate_email_template: pending, complete (with html) or failed (with error).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_email_identities
Read List sending domains
The org's email sending domains with verification status.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
get_email_identity
Read Get a sending domain
One sending domain with its DKIM tokens for DNS setup.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_email_identity
Write Add a sending domain
Register a sending domain (SES) and queue verification; add the returned DNS records. Use the exact domain the From address will be on (example.com, not mail.example.com). Once verified, set its From address with update_email_identity: nothing is sent from it until then.
Arguments
| Field | Type | Description |
|---|---|---|
| domain required | string | |
| mail_from_subdomain | string | Bounce subdomain, default "mail". Change it if mail.<domain> is already a CNAME. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_email_identity
Write Remove a sending domain
Remove a sending domain here and from Amazon SES: email from it stops working. Confirm with the operator first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
verify_email_identity
Write Re-check a sending domain
Check a sending domain's DNS verification now. A failed domain starts verification again.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_email_identity
Write Change a sending domain's From address
Set the From address a sending domain's email goes out from (nothing is sent from the domain until it has one; blank stops sending from it), or, before it's verified, its bounce subdomain (default "mail"). Confirm the address with the operator: it should be a real mailbox.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| from_address | string | The address on the domain, or just the part before the @ ("hello"). |
| mail_from_subdomain | string | One word, such as "mail" or "bounce". Only before verification. |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
list_whatsapp_templates
Read List WhatsApp templates
The org's own WhatsApp templates (draft, in review, approved, rejected), which template each automatic WhatsApp send uses outside the 24-hour window, and the starter templates not yet added. Manager or owner, on a plan with WhatsApp.
Arguments
| Field | Type | Description |
|---|---|---|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
create_whatsapp_template
Write Draft a WhatsApp template
Saves a WhatsApp template draft. It can't send until submitted (submit_whatsapp_template) and approved by Meta. assign_functions sets it for automatic sends that have no template yet.
Arguments
| Field | Type | Description |
|---|---|---|
| friendly_name required | string | Lower_snake key; a starter's key makes this the copy automatic sends use. |
| display_name required | string | |
| body required | string | Message text with {{1}}-style or named variables. |
| category | string |
One of: "UTILITY", "MARKETING"
|
| assign_functions | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
update_whatsapp_template
Write Edit a WhatsApp template
Changes a draft or rejected template (only the fields given). Templates in review or approved can't be edited.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| friendly_name | string | Lower_snake key; a starter's key makes this the copy automatic sends use. |
| display_name | string | |
| body | string | Message text with {{1}}-style or named variables. |
| category | string |
One of: "UTILITY", "MARKETING"
|
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
delete_whatsapp_template
Write Delete a WhatsApp template
PERMANENT. Deletes one of the org's WhatsApp templates; automatic sends that used it fall back to their default. Confirm with the user first.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
submit_whatsapp_template
Write Submit a WhatsApp template to Meta
Sends a draft template to Meta for approval through the org's own WhatsApp Business Account. Meta usually decides within hours; the org is notified. category overrides the template's (UTILITY or MARKETING).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| category | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
add_whatsapp_starter_templates
Write Add WhatsApp starter templates
Adds ready-made starter templates (missing_starter_keys in list_whatsapp_templates, or all missing ones when keys is omitted), submits them to Meta and sets them for their automatic sends where none is chosen.
Arguments
| Field | Type | Description |
|---|---|---|
| keys | array of string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
refresh_whatsapp_template_status
Write Refresh a WhatsApp template's approval status
Asks Meta for a submitted template's current approval status now instead of waiting.
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
assign_whatsapp_template
Write Choose the template for an automatic WhatsApp message
Sets which template an automatic WhatsApp send (function_key from list_whatsapp_templates) uses outside the 24-hour window. A blank template_id clears the choice. The template sends once Meta has approved it.
Arguments
| Field | Type | Description |
|---|---|---|
| function_key required | string | |
| template_id | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
prepare_whatsapp_connection
Write Prepare to connect WhatsApp
Starts (or resumes) connecting an agent to the org's own WhatsApp Business number: picks the number and moves it into the org's Twilio account when needed. readiness says what is left; at "ready" the user finishes with Connect with Facebook on the WhatsApp page, which has to happen in their browser. Manager or owner.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| phone_number | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
cancel_whatsapp_connection
Write Cancel a WhatsApp connection in progress
Abandons an unfinished WhatsApp signup (id from prepare_whatsapp_connection).
Arguments
| Field | Type | Description |
|---|---|---|
| id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
disconnect_whatsapp
Write Disconnect WhatsApp from an agent
Deregisters the agent's WhatsApp sender and switches its WhatsApp channel off (SMS and voice on the number carry on). Customers can no longer reach it on WhatsApp, and the number can't be registered again until the org removes it in WhatsApp Manager. Confirm with the user first. Manager or owner.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |
claim_whatsapp_sandbox
Write Point the WhatsApp sandbox at an agent
Demo and testing only: routes Twilio's shared WhatsApp Sandbox to this agent so WhatsApp can be tried without a real number. It has one inbound slot, so this takes it over from whichever org held it. Manager or owner.
Arguments
| Field | Type | Description |
|---|---|---|
| agent_id required | string | |
| org | string | Organisation slug: required when this authorization covers more than one organisation (see list_orgs) |