Products
Your own helpdesk
When a customer asks for a person, your staff can answer in the Motion 5 inbox, or in the helpdesk or CRM you already use. Webhooks bring the conversation to your system, and this API sends your agents' replies back on WhatsApp.
Overview
- Events in: subscribe a webhook endpoint to
handoff.*andmessage.*events. - Replies out: call the endpoints below with a live key. Conversations are real customers, so test keys get
403 live_key_required. - Side by side: the Motion 5 inbox keeps working. Whoever takes a conversation first has it; the other gets
409 assigned_to_someone_else. The inbox shows when a conversation is being handled from your helpdesk. - Agents are yours: you pass
agent: { id, name }with your helpdesk's ID for the agent and the name the customer should see (they see the first name). There's nothing to set up in Motion 5 per agent.
A handoff, step by step
- 1
The customer asks for a person
They tap Talk to a person in the menu. The bot says someone will reply, and goes quiet. You get
handoff.requestedwith their last 10 messages. - 2
Your helpdesk opens a ticket
Use
conversation.idas the ticket's reference. While it waits, everything the customer sends arrives asmessage.received. - 3
An agent takes it
Call
assignwith the agent. The customer is told "You're now chatting with Ngozi from Your Bank." and you gethandoff.assigned. - 4
They chat
Send replies, photos, documents and voice notes with
messages. Their delivery reports arrive asmessage.status, the customer's messages asmessage.received. - 5
The agent finishes
Call
resolve. The customer is thanked and goes back to the bot menu, and you gethandoff.resolved. It also ends if the customer sends MENU, or after 24 hours without a word from them.
The 24-hour window
WhatsApp lets a business send free-form messages only within 24 hours of the customer's last message. Every conversation carries window.open and window.closes_at. After it closes, assign and messages answer 409 window_closed; the conversation opens again when the customer next writes. A handoff with no word from the customer for 24 hours is resolved with resolved_by: "timeout".
/v1/conversationsQuery
statusopen (default: waiting and active), waiting or active.limit{
"object": "list",
"data": [
{
"object": "conversation",
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"customer": {
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567",
"account_linked": true
},
"handoff": {
"object": "handoff",
"id": "hnd_01JD3W1R2S3T4U5V6W7X8Y9Z0A",
"status": "active",
"assigned_to": {
"id": "agent-42",
"name": "Ngozi Eke",
"via": "api"
},
"requested_at": "2026-11-16T09:31:12.402Z",
"assigned_at": "2026-11-16T09:32:05.000Z",
"resolved_at": null,
"resolved_by": null
},
"window": {
"open": true,
"closes_at": "2026-11-17T09:31:40.000Z"
},
"last_message": {
"object": "message",
"id": "msg_01JD3W2F7G8H9J0K1M2N3P4Q5R",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "image",
"text": "Here's the receipt",
"reply": null,
"media": {
"kind": "image",
"mime_type": "image/jpeg",
"filename": null,
"voice": false,
"url": "https://motion5.dev/v1/messages/msg_01JD3W2F7G8H9J0K1M2N3P4Q5R/media"
},
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:58.530Z"
}
}
]
}/v1/conversations/{id}Query
limit{
"object": "conversation",
"id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"customer": {
"name": "Ada Okon",
"phone": "+2348031234567",
"wa_id": "2348031234567",
"account_linked": true
},
"handoff": {
"object": "handoff",
"id": "hnd_01JD3W1R2S3T4U5V6W7X8Y9Z0A",
"status": "active",
"assigned_to": {
"id": "agent-42",
"name": "Ngozi Eke",
"via": "api"
},
"requested_at": "2026-11-16T09:31:12.402Z",
"assigned_at": "2026-11-16T09:32:05.000Z",
"resolved_at": null,
"resolved_by": null
},
"window": {
"open": true,
"closes_at": "2026-11-17T09:31:40.000Z"
},
"messages": [
{
"object": "message",
"id": "msg_01JD3W2A3B4C5D6E7F8G9H0J1K",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "text",
"text": "I was debited twice for one transfer",
"reply": null,
"media": null,
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:40.118Z"
},
{
"object": "message",
"id": "msg_01JD3W2F7G8H9J0K1M2N3P4Q5R",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "in",
"sender": "customer",
"agent": null,
"type": "image",
"text": "Here's the receipt",
"reply": null,
"media": {
"kind": "image",
"mime_type": "image/jpeg",
"filename": null,
"voice": false,
"url": "https://motion5.dev/v1/messages/msg_01JD3W2F7G8H9J0K1M2N3P4Q5R/media"
},
"status": "received",
"error": null,
"created_at": "2026-11-16T09:31:58.530Z"
},
{
"object": "message",
"id": "msg_01JD3W3C4D5E6F7G8H9J0K1M2N",
"conversation_id": "cus_01JD3V0QH5M7X8Z9A1B2C3D4E5",
"direction": "out",
"sender": "agent",
"agent": {
"id": "agent-42",
"name": "Ngozi Eke",
"via": "api"
},
"type": "text",
"text": "Hi Ada, I'm looking into it now.",
"reply": null,
"media": null,
"status": "sent",
"error": null,
"created_at": "2026-11-16T09:32:20.004Z"
}
]
}/v1/conversations/{id}/assign409 assigned_to_someone_else.Body
agent.id. _ - @ : +.agent.namecurl https://motion5.dev/v1/conversations/cus_01JD3V0QH5M7X8Z9A1B2C3D4E5/assign \
-H "Authorization: Bearer $MOTION5_LIVE_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent": { "id": "agent-42", "name": "Ngozi Eke" } }'Returns the conversation, with the active handoff.
/v1/conversations/{id}/messagesText
JSON body
agent{ id, name }, as for assign.textcurl https://motion5.dev/v1/conversations/cus_01JD3V0QH5M7X8Z9A1B2C3D4E5/messages \
-H "Authorization: Bearer $MOTION5_LIVE_KEY" \
-H "Idempotency-Key: reply-7731-1" \
-H "Content-Type: application/json" \
-d '{ "agent": { "id": "agent-42", "name": "Ngozi Eke" }, "text": "Hi Ada, I can see the double debit. The reversal is on its way." }'Photos, documents and voice notes
Send multipart/form-data instead, with the file and the agent as form fields. Files can be up to 4 MB.
Form fields
fileagent_idagent_namecaptioncurl https://motion5.dev/v1/conversations/cus_01JD3V0QH5M7X8Z9A1B2C3D4E5/messages \
-H "Authorization: Bearer $MOTION5_LIVE_KEY" \
-F "file=@dispute-form.pdf;type=application/pdf" \
-F "agent_id=agent-42" -F "agent_name=Ngozi Eke" \
-F "caption=Please fill this and send it back"Returns 201 with the message (status: "sent"); message.status events follow as it's delivered and read. Errors: 409 window_closed, 409 assigned_to_someone_else, 400 empty_message, message_too_long, unsupported_file_type or file_too_large, 502 whatsapp_refused.
/v1/conversations/{id}/resolveBody
agent{ id, name }.Returns the conversation with the resolved handoff. If there's no open handoff: 409 no_open_handoff.
/v1/messages/{id}/mediaContent-Type. The media.url on messages points here; fetch it with your API key.curl -o receipt.jpg https://motion5.dev/v1/messages/msg_01JD3W2F7G8H9J0K1M2N3P4Q5R/media \
-H "Authorization: Bearer $MOTION5_LIVE_KEY"Download what you need to keep
404 media_expired, so save files to your helpdesk when they arrive.Objects
Conversation
One customer's chat with your bank. Its ID is the customer's, so it stays the same across handoffs.
idcus_.customername (their WhatsApp profile name), phone (E.164), wa_id, and account_linked: whether the number matched an account at your bank.handoffwindowlast_messageHandoff
statuswaiting, active (an agent has it) or resolved.assigned_toid, name and via: api (your helpdesk) or inbox (the Motion 5 inbox).resolved_byagent, customer (sent MENU) or timeout.requested_at, assigned_at, resolved_atMessage
directionin from the customer, out to them.sendercustomer, bot, agent, or system (notices like "You're now chatting with…"). agentid, name, via.typetext, image, audio, video, sticker, document, reply (the customer tapped a button or menu row), interactive (a bot menu or PIN request), form (the customer completed a secure form such as their PIN; what they typed is never included) or unsupported.textreplyid and title.mediakind, mime_type, filename, voice (a recorded voice note) and url.statusout: sent, delivered, read or failed (with error). For in: received.