Wabi

Conversations API

The inbox: assignment, turn state, notes and resolution. 19 ops: list_conversations, get_inbox_counts, get_conversation, reply_to_conversation, assign_conversation, claim_conversation, add_conversation_note, tag_conversation, update_conversation, set_turn_state, escalate_conversation, resolve_conver

The inbox: assignment, turn state, notes and resolution.

list_conversations

read

List conversations · POST /api/v1/list_conversations · scope conversations:read or GET …?input=

The inbox: conversations in one queue view, with the contact and the last message. Views: all (Every open or pending conversation.); needs_first_response (A customer is waiting and nobody has answered them substantively yet.); needs_reply (A customer turn is waiting for a substantive answer (customer_waiting, acknowledged or escalated).); unassigned (Open conversations without an assignee.); mine (Open conversations assigned to the caller.); ai (Handled by an AI agent, with no human takeover.); human (Handled by a person.); escalated (Handed to a human by an AI agent or a rule.); high_priority (Priority high or urgent.); sla_at_risk (Waiting for a reply and due within 30 minutes or overdue.); window_expiring (The 24-hour service window closes within the warning threshold (default 2 hours).); waiting_on_customer (Answered, or waiting for information from the customer.); resolved (Resolved conversations, newest first.). Filter by assignee ("me" or a user id), team, tag, priority, contact or sender, or search q (contact name, phone, email, or a tag). Returns conversations (turn_state, waiting_since, window_expires_at, sla_due_at…), total and the next offset. Use get_inbox_counts for every view's count.

curl -X POST https://getwabi.dev/api/v1/list_conversations \  -H "Authorization: Bearer wabi_…"

get_inbox_counts

read

Get inbox counts · POST /api/v1/get_inbox_counts · scope conversations:read or GET …?input=

How many conversations each inbox view holds now (needs_reply, unassigned, mine, escalated, window_expiring, sla_at_risk…). Use it for a quick operational picture before list_conversations.

curl -X POST https://getwabi.dev/api/v1/get_inbox_counts \  -H "Authorization: Bearer wabi_…"

get_conversation

read

Get a conversation · POST /api/v1/get_conversation · scope conversations:read or GET …?input=

One conversation with its full timeline: every message (direction, type, text, media, location, template, sender, delivery and read receipts, errors, and whether it counted as an answer), internal notes and assignment/escalation history; plus the contact's profile and their separate messaging, consent, engagement, support and campaign states. Use before replying or handing off.

curl -X POST https://getwabi.dev/api/v1/get_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

reply_to_conversation

write

Reply in a conversation · POST /api/v1/reply_to_conversation · scope conversations:write

Sends a reply to the conversation's customer through the messaging engine (send_message, with all its safeguards). Free-form text (or a saved reply, filled with variables) while the 24-hour service window is open; when it has closed, pass template { name, language, components } and that is sent instead; text alone after the window is a 422 window_closed. A person replying from the dashboard takes the conversation over from its AI agent. Returns the mode used (free_form or template) and the message id.

curl -X POST https://getwabi.dev/api/v1/reply_to_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

assign_conversation

write

Assign a conversation · POST /api/v1/assign_conversation · scope conversations:write

Assigns a conversation to a member ("me", a user id, or null to unassign) and/or a team, or picks one automatically with strategy least_loaded (fewest open conversations) or round_robin (among the team, or every non-viewer member). An optional note is kept as an internal note. Emits conversation.assigned. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/assign_conversation \  -H "Authorization: Bearer wabi_…"

claim_conversation

write

Claim a conversation · POST /api/v1/claim_conversation · scope conversations:write

Assigns an unassigned conversation to the caller (a person). Someone else's conversation is a 409; use assign_conversation to take it over. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/claim_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

add_conversation_note

write

Add an internal note · POST /api/v1/add_conversation_note · scope conversations:write

Adds an internal note to a conversation (never sent to the customer), optionally mentioning members by user id. Returns the note.

curl -X POST https://getwabi.dev/api/v1/add_conversation_note \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10","body":"It would save us a trip to Meta Business Manager."}'

tag_conversation

write

Tag a conversation · POST /api/v1/tag_conversation · scope conversations:write

Adds and removes conversation tags (lowercased). Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/tag_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

update_conversation

write

Update a conversation · POST /api/v1/update_conversation · scope conversations:write

Sets a conversation's priority (low, normal, high, urgent: the SLA target follows), category or language. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/update_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

set_turn_state

write

Set the customer-turn state · POST /api/v1/set_turn_state · scope conversations:write

Records an explicit disposition of the customer's turn when no message says it: answered (handled elsewhere, e.g. by phone), needs_info, awaiting_customer, acknowledged or customer_waiting (still owed an answer). Automatic messages never answer a turn, so use this for answers given outside WhatsApp. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/set_turn_state \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10","state":"customer_waiting"}'

escalate_conversation

write

Escalate a conversation · POST /api/v1/escalate_conversation · scope conversations:write

Hands a conversation to a human: turn_state escalated, human takeover on (AI agents stop answering), priority raised to at least high, optionally to a team or person. AI agents call it with the reason, a summary (or note) for the person and their hand-off packet (handoff: question, summary, sources, attempted actions, recommended next step, agent_id, session_id, confidence). Emits conversation.escalated (a customer webhook event) once per agent session. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/escalate_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"reason":"reason"}'

resolve_conversation

write

Resolve a conversation · POST /api/v1/resolve_conversation · scope conversations:write

Marks a conversation resolved, with an optional internal note. A later customer message opens a new conversation. Emits conversation.resolved. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/resolve_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

reopen_conversation

write

Reopen a conversation · POST /api/v1/reopen_conversation · scope conversations:write

Reopens a resolved conversation as waiting for a reply (counted in the reopen rate). A 409 when the customer already has a newer open conversation on the same number. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/reopen_conversation \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10"}'

set_human_takeover

write

Take over from the AI agent · POST /api/v1/set_human_takeover · scope conversations:write

on: a person takes the conversation over and AI agents stop answering it (they read human_takeover); off: hands it back to the agent. Returns the conversation.

curl -X POST https://getwabi.dev/api/v1/set_human_takeover \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"conversation":"6f1c2e0a-4b7d-4c2e-9a51-0d3b8e7f9a10","on":false}'

list_saved_replies

read

List saved replies · POST /api/v1/list_saved_replies · scope conversations:read or GET …?input=

The organization's saved (canned) replies with their {{variables}}. Send one with reply_to_conversation { saved_reply: <shortcut> }.

curl -X POST https://getwabi.dev/api/v1/list_saved_replies \  -H "Authorization: Bearer wabi_…"

save_saved_reply

write

Save a saved reply · POST /api/v1/save_saved_reply · scope conversations:write

Creates or updates (by shortcut) a saved reply. The body may use {{contact.name}}, {{contact.first_name}}, {{contact.phone}}, {{contact.email}}, {{contact.<attribute>}} and your own {{variables}}. Returns it.

curl -X POST https://getwabi.dev/api/v1/save_saved_reply \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"shortcut":"shortcut","name":"Support","body":"It would save us a trip to Meta Business Manager."}'

delete_saved_reply

write

Delete a saved reply · POST /api/v1/delete_saved_reply · scope conversations:write

Deletes a saved reply by shortcut.

curl -X POST https://getwabi.dev/api/v1/delete_saved_reply \  -H "Authorization: Bearer wabi_…" \  -H "Content-Type: application/json" \  -d '{"shortcut":"shortcut"}'

get_inbox_settings

read

Get inbox settings · POST /api/v1/get_inbox_settings · scope conversations:read or GET …?input=

First-response SLA targets by priority (minutes), when window.expiring fires (minutes before a window closes) and when conversation.needs_reply fires (minutes a turn waited).

curl -X POST https://getwabi.dev/api/v1/get_inbox_settings \  -H "Authorization: Bearer wabi_…"

update_inbox_settings

writeowner or admin

Update inbox settings · POST /api/v1/update_inbox_settings · scope conversations:write

Changes the SLA targets, the window warning threshold or the needs-reply delay. Admins only. Returns the settings.

curl -X POST https://getwabi.dev/api/v1/update_inbox_settings \  -H "Authorization: Bearer wabi_…"