Motion 5Book a demo

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.* and message.* 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. 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.requested with their last 10 messages.

  2. 2

    Your helpdesk opens a ticket

    Use conversation.id as the ticket's reference. While it waits, everything the customer sends arrives as message.received.

  3. 3

    An agent takes it

    Call assign with the agent. The customer is told "You're now chatting with Ngozi from Your Bank." and you get handoff.assigned.

  4. 4

    They chat

    Send replies, photos, documents and voice notes with messages. Their delivery reports arrive as message.status, the customer's messages as message.received.

  5. 5

    The agent finishes

    Call resolve. The customer is thanked and goes back to the bot menu, and you get handoff.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".

GET/v1/conversations
Conversations with an open handoff: waiting for a person, or with one. Longest waiting first. Use it to fill a queue when your helpdesk starts, or to catch up after downtime.

Query

status
stringoptional
open (default: waiting and active), waiting or active.
limit
integeroptional
1 to 200. Default 100.
Response
{
  "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"
      }
    }
  ]
}
GET/v1/conversations/{id}
One conversation with its messages, oldest first: what the bot said, what the customer sent, and every agent reply.

Query

limit
integeroptional
How many of the latest messages, 1 to 200. Default 50.
Response
{
  "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"
    }
  ]
}
POST/v1/conversations/{id}/assign
Give the conversation to one of your agents. The customer is told who's helping them. Calling it again for the same agent does nothing; for a different agent while one has it, you get 409 assigned_to_someone_else.

Body

agent.id
stringrequired
Your helpdesk's ID for the agent: 1 to 64 letters, digits or . _ - @ : +.
agent.name
stringrequired
The name the customer sees, 2 to 60 characters. The message uses the first name.
curl 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.

POST/v1/conversations/{id}/messages
Send a reply from an agent. If the conversation isn't already theirs, it's assigned to them first (so the customer hears who's helping). Use an Idempotency-Key so a retry never sends twice.

Text

JSON body

agent
objectrequired
{ id, name }, as for assign.
text
stringrequired
Up to 4,000 characters. WhatsApp formatting works: *bold*, _italic_, ~strike~.
curl 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

file
filerequired
JPG or PNG (sent as a photo); PDF, Word, Excel or plain text (a document); OGG/Opus audio (a voice note).
agent_id
stringrequired
Your ID for the agent.
agent_name
stringrequired
The name the customer sees.
caption
stringoptional
Text under a photo or document, up to 1,000 characters. Voice notes have none.
curl 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.

POST/v1/conversations/{id}/resolve
Hand the conversation back to the bot. The customer is thanked and told they can send MENU any time.

Body

agent
objectoptional
Who resolved it, for your bank's audit log: { id, name }.

Returns the conversation with the resolved handoff. If there's no open handoff: 409 no_open_handoff.

GET/v1/messages/{id}/media
The file in a customer's message (photo, voice note, video, sticker or document), as raw bytes with its Content-Type. The media.url on messages points here; fetch it with your API key.
Example
curl -o receipt.jpg https://motion5.dev/v1/messages/msg_01JD3W2F7G8H9J0K1M2N3P4Q5R/media \
  -H "Authorization: Bearer $MOTION5_LIVE_KEY"

Download what you need to keep

WhatsApp keeps media for 30 days, and Motion 5 doesn't copy it. After that this answers 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.

id
string
Starts with cus_.
customer
object
name (their WhatsApp profile name), phone (E.164), wa_id, and account_linked: whether the number matched an account at your bank.
handoff
object or null
The open handoff, if any.
window
object
open and closes_at: the 24-hour window.
last_message
object
In lists only: the newest message.

Handoff

status
string
waiting, active (an agent has it) or resolved.
assigned_to
object or null
id, name and via: api (your helpdesk) or inbox (the Motion 5 inbox).
resolved_by
string or null
agent, customer (sent MENU) or timeout.
requested_at, assigned_at, resolved_at
time or null
When each step happened.

Message

direction
string
in from the customer, out to them.
sender
string
customer, bot, agent, or system (notices like "You're now chatting with…").
agent
object or null
For agent messages: id, name, via.
type
string
text, 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.
text
string or null
The text, a caption, or the title of the button tapped.
reply
object or null
For taps: the button's id and title.
media
object or null
kind, mime_type, filename, voice (a recorded voice note) and url.
status
string
For out: sent, delivered, read or failed (with error). For in: received.