MCP tools — Inbox
Three tools to list conversations, read message history, and send/reply to contacts.
The Inbox is where the agent does customer-care work. Three tools cover the loop: discover conversations, read history, send the right message.
| Tool | Annotation | Purpose |
|---|---|---|
list_conversations |
IsReadOnly, IsIdempotent |
Recent conversations + 24h window state |
get_conversation |
IsReadOnly, IsIdempotent |
Full message history for a contact |
send_message |
IsDestructive(false) |
Send text or template, with the right policy |
list_conversations
List recent conversations (contacts with messages). Ordered by most recent message. Excludes broadcast messages. Each row exposes window_open_until — the deadline of the 24h customer-care window during which free-form text replies are allowed; null if the window is closed (only template messages can be sent).
| Input | Type | Notes |
|---|---|---|
unread_only |
boolean | default false |
limit |
integer | default 25 |
The window_open_until field is the most useful one for an agent — it tells you whether you can reply with free-form text or must use a template.
get_conversation
Get messages for a contact conversation in chronological order. Excludes broadcast messages.
| Input | Type | Notes |
|---|---|---|
contact_id |
UUID | required |
limit |
integer | default 50 |
Returns messages oldest→newest so the agent can read the thread top-down.
send_message
Send a WhatsApp message to a contact, or reply to one. Two types:
text— free-form, only works inside the 24h customer service window. Standard "answer a customer" action.template— Meta-approved template. Works any time, including outside the 24h window.
| Input | Type | Notes |
|---|---|---|
contact_id |
UUID | one of |
phone |
string | one of (auto-creates contact) |
type |
string | text or template |
text |
string | required when type=text |
template_id |
UUID | required when type=template |
language |
string | optional; auto-fallback if not approved |
variables |
object | required when the template has placeholders |
The agent should call list_conversations first, look at window_open_until, then pick text if the window is open or template otherwise. Sending free-form text outside the window returns Meta error 131047 and the message lands in the inbox with status: failed.