MCP tools

Every call needs Authorization: Bearer <key>. 11 calls:

• MCP tool: check whether a number is on iMessage: POST /v1/mcp/tools/check_imessage
• MCP tool: get a contact by id or phone: POST /v1/mcp/tools/get_contact
• MCP tool: get a conversation and its messages: POST /v1/mcp/tools/get_conversation
• MCP tool: get a message’s status and timeline: POST /v1/mcp/tools/get_message_status
• MCP tool: hand a conversation to a person: POST /v1/mcp/tools/handoff_to_human
• MCP tool: list recent conversations: POST /v1/mcp/tools/list_conversations
• MCP tool: list lines with health and capacity: POST /v1/mcp/tools/list_lines
• MCP tool: reply in a conversation: POST /v1/mcp/tools/reply_to_conversation
• MCP tool: search contacts: POST /v1/mcp/tools/search_contacts
• MCP tool: send a message: POST /v1/mcp/tools/send_message
• MCP tool: create or update a contact by phone: POST /v1/mcp/tools/upsert_contact

MCP tool: check whether a number is on iMessage

POST /v1/mcp/tools/check_imessage

Check whether a number can receive iMessage (cached for 30 days) Called by the bubbl3 MCP server with the client’s API key or service identity token; runs POST /v1/lookup with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
phone	string	Yes	Phone number in E.164 format.

Response 200

Field	Type	Description
cached	boolean
checked_at	string (date-time)	ISO 8601 timestamp.
imessage	boolean
phone	string	Phone number in E.164 format.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: get a contact by id or phone

POST /v1/mcp/tools/get_contact

Get one contact by id or phone Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/contacts/:id with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
contact_id	string	No	Contact id (ctc_...).
phone	string	No	Phone number in E.164 format.

Response 200

Field	Type	Description
assigned_line_id	string or null	Line id (ln_...).
capability_checked_at	string (date-time) or null	ISO 8601 timestamp.
company	string or null
consent_at	string (date-time) or null	ISO 8601 timestamp.
consent_source	string or null
consent_status	enum	One of: unknown, opted_in, opted_out.
created_at	string (date-time)	ISO 8601 timestamp.
email	string or null
fields	object
first_name	string or null
first_reply_at	string (date-time) or null	ISO 8601 timestamp.
id	string	Contact id (ctc_...).
imessage_capable	boolean or null
labels	string[]
last_inbound_at	string (date-time) or null	ISO 8601 timestamp.
last_name	string or null
last_outbound_at	string (date-time) or null	ISO 8601 timestamp.
owner_user_id	string (uuid) or null
phone	string	Phone number in E.164 format.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: get a conversation and its messages

POST /v1/mcp/tools/get_conversation

Get the messages in a conversation Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/conversations/:id with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
conversation_id	string	Yes	Conversation id (cnv_...).
limit	integer	No	Most recent messages to return. From 1 to 200. Default 50.

Response 200

Field	Type	Description
assignee_user_id	string (uuid) or null
contact	object
contact.company	string or null
contact.first_name	string or null
contact.id	string	Contact id (ctc_...).
contact.last_name	string or null
contact.phone	string	Phone number in E.164 format.
created_at	string (date-time)	ISO 8601 timestamp.
handled_by	string
id	string	Conversation id (cnv_...).
labels	string[]
last_message	object or null
last_message.direction	enum	One of: outbound, inbound.
last_message.id	string	Message id (msg_...).
last_message.preview	string	Up to 200 characters.
last_message_at	string (date-time) or null	ISO 8601 timestamp.
line_id	string or null	Line id (ln_...).
messages	object[]
messages[].body	string
messages[].channel	enum	One of: imessage, sms.
messages[].contact_id	string	Contact id (ctc_...).
messages[].conversation_id	string	Conversation id (cnv_...).
messages[].created_at	string (date-time)	ISO 8601 timestamp.
messages[].delivered_at	string (date-time) or null	ISO 8601 timestamp.
messages[].direction	enum	One of: outbound, inbound.
messages[].error_code	string or null
messages[].error_details	object or null
messages[].external_id	string or null
messages[].from	string or null	Phone number in E.164 format.
messages[].id	string	Message id (msg_...).
messages[].is_test	boolean
messages[].line_id	string or null	Line id (ln_...).
messages[].media	object[]
messages[].media[].filename	string or null
messages[].media[].mime	string or null
messages[].media[].size	integer or null	From 0 to 9007199254740991.
messages[].media[].url	string
messages[].metadata	object
messages[].read_at	string (date-time) or null	ISO 8601 timestamp.
messages[].scheduled_for	string (date-time) or null	ISO 8601 timestamp.
messages[].sent_at	string (date-time) or null	ISO 8601 timestamp.
messages[].sent_by_staff	boolean
messages[].source	enum or null	One of: api, dashboard, workflow, agent, outreach, mcp.
messages[].status	enum	One of: queued, scheduled, sending, sent, delivered, read, failed, received.
messages[].to	string or null	Phone number in E.164 format.
messages[].updated_at	string (date-time)	ISO 8601 timestamp.
messages_next_cursor	string or null	Pass as messages_cursor for older messages; null when there are none.
notes	object[]	The most recent internal notes, newest first.
notes[].author_user_id	string (uuid) or null
notes[].body	string
notes[].conversation_id	string	Conversation id (cnv_...).
notes[].created_at	string (date-time)	ISO 8601 timestamp.
notes[].id	string (uuid)
snoozed_until	string (date-time) or null	ISO 8601 timestamp.
status	enum	One of: open, snoozed, closed.
team_id	string (uuid) or null
unread_count	integer	From 0 to 9007199254740991.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: get a message’s status and timeline

POST /v1/mcp/tools/get_message_status

Get a message’s status and delivery timeline Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/messages/:id/events with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
message_id	string	Yes	Message id (msg_...).

Response 200

Field	Type	Description
events	object[]
events[].detail	object	Event-specific detail, e.g. the deferral reason.
events[].id	string (uuid)
events[].occurred_at	string (date-time)	ISO 8601 timestamp.
events[].type	enum	One of: accepted, routed, capability_checked, deferred, rejected, sending, sent, delivered, read, failed, retried, fallback_sms, received, receipt_missing.
message	object
message.body	string
message.channel	enum	One of: imessage, sms.
message.contact_id	string	Contact id (ctc_...).
message.conversation_id	string	Conversation id (cnv_...).
message.created_at	string (date-time)	ISO 8601 timestamp.
message.delivered_at	string (date-time) or null	ISO 8601 timestamp.
message.direction	enum	One of: outbound, inbound.
message.error_code	string or null
message.error_details	object or null
message.external_id	string or null
message.from	string or null	Phone number in E.164 format.
message.id	string	Message id (msg_...).
message.is_test	boolean
message.line_id	string or null	Line id (ln_...).
message.media	object[]
message.media[].filename	string or null
message.media[].mime	string or null
message.media[].size	integer or null	From 0 to 9007199254740991.
message.media[].url	string
message.metadata	object
message.read_at	string (date-time) or null	ISO 8601 timestamp.
message.scheduled_for	string (date-time) or null	ISO 8601 timestamp.
message.sent_at	string (date-time) or null	ISO 8601 timestamp.
message.sent_by_staff	boolean
message.source	enum or null	One of: api, dashboard, workflow, agent, outreach, mcp.
message.status	enum	One of: queued, scheduled, sending, sent, delivered, read, failed, received.
message.to	string or null	Phone number in E.164 format.
message.updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: hand a conversation to a person

POST /v1/mcp/tools/handoff_to_human

Hand the conversation to a person and notify the assigned team Called by the bubbl3 MCP server with the client’s API key or service identity token; runs PATCH /v1/conversations/:id with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
conversation_id	string	Yes	Conversation id (cnv_...).
reason	string	Yes	Up to 500 characters.
team_id	string (uuid)	No

Response 200

Field	Type	Description
conversation	object
conversation.assignee_user_id	string (uuid) or null
conversation.contact	object
conversation.contact.company	string or null
conversation.contact.first_name	string or null
conversation.contact.id	string	Contact id (ctc_...).
conversation.contact.last_name	string or null
conversation.contact.phone	string	Phone number in E.164 format.
conversation.created_at	string (date-time)	ISO 8601 timestamp.
conversation.handled_by	string
conversation.id	string	Conversation id (cnv_...).
conversation.labels	string[]
conversation.last_message	object or null
conversation.last_message.direction	enum	One of: outbound, inbound.
conversation.last_message.id	string	Message id (msg_...).
conversation.last_message.preview	string	Up to 200 characters.
conversation.last_message_at	string (date-time) or null	ISO 8601 timestamp.
conversation.line_id	string or null	Line id (ln_...).
conversation.snoozed_until	string (date-time) or null	ISO 8601 timestamp.
conversation.status	enum	One of: open, snoozed, closed.
conversation.team_id	string (uuid) or null
conversation.unread_count	integer	From 0 to 9007199254740991.
conversation.updated_at	string (date-time)	ISO 8601 timestamp.
handed_off	boolean	False when a person already handled it; the team and note were still applied.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: list recent conversations

POST /v1/mcp/tools/list_conversations

List recent conversations Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/conversations with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
assignee	enum	No	One of: me, unassigned, any. Default "any".
limit	integer	No	From 1 to 100. Default 20.
status	enum	No	One of: open, snoozed, closed.

Response 200

Field	Type	Description
data	object[]
data[].assignee_user_id	string (uuid) or null
data[].contact	object
data[].contact.company	string or null
data[].contact.first_name	string or null
data[].contact.id	string	Contact id (ctc_...).
data[].contact.last_name	string or null
data[].contact.phone	string	Phone number in E.164 format.
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].handled_by	string
data[].id	string	Conversation id (cnv_...).
data[].labels	string[]
data[].last_message	object or null
data[].last_message.direction	enum	One of: outbound, inbound.
data[].last_message.id	string	Message id (msg_...).
data[].last_message.preview	string	Up to 200 characters.
data[].last_message_at	string (date-time) or null	ISO 8601 timestamp.
data[].line_id	string or null	Line id (ln_...).
data[].snoozed_until	string (date-time) or null	ISO 8601 timestamp.
data[].status	enum	One of: open, snoozed, closed.
data[].team_id	string (uuid) or null
data[].unread_count	integer	From 0 to 9007199254740991.
data[].updated_at	string (date-time)	ISO 8601 timestamp.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: list lines with health and capacity

POST /v1/mcp/tools/list_lines

List lines with health and the new-contact capacity left today Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/lines with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
pool_id	string	No	Pool id (pool_...).

Response 200

Field	Type	Description
data	object[]
data[].contact_card	object
data[].contact_card.image_url	string	Up to 2048 characters.
data[].contact_card.name	string	Up to 100 characters.
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].daily_new_cap	integer	From 0 to 9007199254740991.
data[].display_name	string or null
data[].health_score	integer	From 0 to 100.
data[].id	string	Line id (ln_...).
data[].is_sandbox	boolean
data[].phone	string	Phone number in E.164 format.
data[].pool_id	string or null	Pool id (pool_...).
data[].state	enum	One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired.
data[].state_changed_at	string (date-time) or null	ISO 8601 timestamp.
data[].state_reason	string or null
data[].usage_today	object
data[].usage_today.day	string (date)	Usage day in America/New_York, rolling over at 3 AM.
data[].usage_today.new_contacts	integer	From 0 to 9007199254740991.
data[].usage_today.new_contacts_cap	integer	From 0 to 9007199254740991.
data[].usage_today.sends	integer	From 0 to 9007199254740991.
data[].usage_today.sends_cap	integer	From 0 to 9007199254740991.
data[].warmup_day	integer	From 0 to 9007199254740991.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: reply in a conversation

POST /v1/mcp/tools/reply_to_conversation

Reply in an existing conversation. Never message contacts who opted out. When the workspace requires consent, only contacts who opted in can be messaged. Sends outside 9 AM–8 PM in the contact’s local time are deferred. Until a contact replies, messages must be under 300 characters, contain no links, media, phone numbers or emails, and at most 3 can be sent. Called by the bubbl3 MCP server with the client’s API key or service identity token; runs POST /v1/conversations/:id/messages with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
body	string	Yes	Up to 2000 characters.
conversation_id	string	Yes	Conversation id (cnv_...).
idempotency_key	string	No	Optional. Sent as the Idempotency-Key header: retrying with the same key returns the first message instead of sending again. Keys starting with outreach:, workflow: or agent: are refused. Up to 255 characters.

Response 200

Field	Type	Description
body	string
channel	enum	One of: imessage, sms.
contact_id	string	Contact id (ctc_...).
conversation_id	string	Conversation id (cnv_...).
created_at	string (date-time)	ISO 8601 timestamp.
delivered_at	string (date-time) or null	ISO 8601 timestamp.
direction	enum	One of: outbound, inbound.
error_code	string or null
error_details	object or null
external_id	string or null
from	string or null	Phone number in E.164 format.
id	string	Message id (msg_...).
is_test	boolean
line_id	string or null	Line id (ln_...).
media	object[]
media[].filename	string or null
media[].mime	string or null
media[].size	integer or null	From 0 to 9007199254740991.
media[].url	string
metadata	object
read_at	string (date-time) or null	ISO 8601 timestamp.
scheduled_for	string (date-time) or null	ISO 8601 timestamp.
sent_at	string (date-time) or null	ISO 8601 timestamp.
sent_by_staff	boolean
source	enum or null	One of: api, dashboard, workflow, agent, outreach, mcp.
status	enum	One of: queued, scheduled, sending, sent, delivered, read, failed, received.
to	string or null	Phone number in E.164 format.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: search contacts

POST /v1/mcp/tools/search_contacts

Search contacts Called by the bubbl3 MCP server with the client’s API key or service identity token; runs GET /v1/contacts with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
limit	integer	No	From 1 to 100. Default 20.
query	string	Yes	Name, phone, email or company. Up to 100 characters.

Response 200

Field	Type	Description
data	object[]
data[].assigned_line_id	string or null	Line id (ln_...).
data[].capability_checked_at	string (date-time) or null	ISO 8601 timestamp.
data[].company	string or null
data[].consent_at	string (date-time) or null	ISO 8601 timestamp.
data[].consent_source	string or null
data[].consent_status	enum	One of: unknown, opted_in, opted_out.
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].email	string or null
data[].fields	object
data[].first_name	string or null
data[].first_reply_at	string (date-time) or null	ISO 8601 timestamp.
data[].id	string	Contact id (ctc_...).
data[].imessage_capable	boolean or null
data[].labels	string[]
data[].last_inbound_at	string (date-time) or null	ISO 8601 timestamp.
data[].last_name	string or null
data[].last_outbound_at	string (date-time) or null	ISO 8601 timestamp.
data[].owner_user_id	string (uuid) or null
data[].phone	string	Phone number in E.164 format.
data[].updated_at	string (date-time)	ISO 8601 timestamp.
next_cursor	string or null	Pass as cursor to get the next page; null at the end.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: send a message

POST /v1/mcp/tools/send_message

Send a message. Never message contacts who opted out. When the workspace requires consent, only contacts who opted in can be messaged. Sends outside 9 AM–8 PM in the contact’s local time are deferred. Until a contact replies, messages must be under 300 characters, contain no links, media, phone numbers or emails, and at most 3 can be sent. Called by the bubbl3 MCP server with the client’s API key or service identity token; runs POST /v1/messages with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
body	string	Yes	Up to 2000 characters.
contact_id	string	No	Contact id (ctc_...).
fallback	boolean	No	Allow SMS if the contact is not on iMessage.
idempotency_key	string	No	Optional. Sent as the Idempotency-Key header: retrying with the same key returns the first message instead of sending again. Keys starting with outreach:, workflow: or agent: are refused. Up to 255 characters.
pool_id	string	No	Pool id (pool_...).
to	string	No	Recipient phone number in E.164. Provide to or contact_id.

Response 200

Field	Type	Description
body	string
channel	enum	One of: imessage, sms.
contact_id	string	Contact id (ctc_...).
conversation_id	string	Conversation id (cnv_...).
created_at	string (date-time)	ISO 8601 timestamp.
delivered_at	string (date-time) or null	ISO 8601 timestamp.
direction	enum	One of: outbound, inbound.
error_code	string or null
error_details	object or null
external_id	string or null
from	string or null	Phone number in E.164 format.
id	string	Message id (msg_...).
is_test	boolean
line_id	string or null	Line id (ln_...).
media	object[]
media[].filename	string or null
media[].mime	string or null
media[].size	integer or null	From 0 to 9007199254740991.
media[].url	string
metadata	object
read_at	string (date-time) or null	ISO 8601 timestamp.
scheduled_for	string (date-time) or null	ISO 8601 timestamp.
sent_at	string (date-time) or null	ISO 8601 timestamp.
sent_by_staff	boolean
source	enum or null	One of: api, dashboard, workflow, agent, outreach, mcp.
status	enum	One of: queued, scheduled, sending, sent, delivered, read, failed, received.
to	string or null	Phone number in E.164 format.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

MCP tool: create or update a contact by phone

POST /v1/mcp/tools/upsert_contact

Create a contact or update the one with this phone number. Does not change consent Called by the bubbl3 MCP server with the client’s API key or service identity token; runs PATCH /v1/contacts/:id with the same permissions and limits. Pass idempotency_key in the input, not the header.

Headers

Name	Type	Required	Description
x-workspace-id	string	No	Workspace for session (JWT) callers. API keys carry their own workspace.

Request body

Field	Type	Required	Description
company	string	No	Up to 200 characters.
email	string (email)	No	Up to 254 characters.
fields	object	No
first_name	string	No	Up to 100 characters.
last_name	string	No	Up to 100 characters.
phone	string	Yes	Phone number in E.164 format.

Response 200

Field	Type	Description
contact	object
contact.assigned_line_id	string or null	Line id (ln_...).
contact.capability_checked_at	string (date-time) or null	ISO 8601 timestamp.
contact.company	string or null
contact.consent_at	string (date-time) or null	ISO 8601 timestamp.
contact.consent_source	string or null
contact.consent_status	enum	One of: unknown, opted_in, opted_out.
contact.created_at	string (date-time)	ISO 8601 timestamp.
contact.email	string or null
contact.fields	object
contact.first_name	string or null
contact.first_reply_at	string (date-time) or null	ISO 8601 timestamp.
contact.id	string	Contact id (ctc_...).
contact.imessage_capable	boolean or null
contact.labels	string[]
contact.last_inbound_at	string (date-time) or null	ISO 8601 timestamp.
contact.last_name	string or null
contact.last_outbound_at	string (date-time) or null	ISO 8601 timestamp.
contact.owner_user_id	string (uuid) or null
contact.phone	string	Phone number in E.164 format.
contact.updated_at	string (date-time)	ISO 8601 timestamp.
created	boolean

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.