Reply in a conversation
POST/v1/agents/:agentId/conversations/:conversationId/messages
x-scope: "conversations:write"
x-rate-limit-per-minute: 20
Sends a text reply to the customer on the conversation's channel, as your team. It shows
in the dashboard as written by the person who created the key. When the agent's
ai_handoff_enabled is on, it pauses the AI for the agent's handoff window like any
teammate's reply (when it is off, the AI keeps answering); when the pause ends, the AI may
write once more if follow-ups are on for the channel (resumeConversationAi or
ai_enabled: false prevents it). It never assigns the conversation.
Refused before anything is saved (422): channel_not_supported on a channel Mojeeb
can't send on (TikTok), and messaging_window_closed on WhatsApp, Facebook or Instagram
when the customer hasn't written in the last 24 hours (on WhatsApp, send a template with
sendWhatsAppTemplate instead). A refused reply isn't stored for its Idempotency-Key,
and until 60 seconds after the refused request that key answers
409 idempotency_key_in_progress: once the cause has passed, send it again with a new
key. The reply is sent after the response: it starts queued and its status moves on
to sent, delivered, read or failed; follow it with getConversationMessage. On a website conversation it is stored as sent and appears in
the open chat.
Request
Responses
- 201
- 401
- 403
- 404
- 409
- 413
- 422
- 429
- 500
- 503
The reply as saved (a replay of it when Idempotent-Replayed is true).
Response Headers
Correlation id for this request — paste into support tickets.
Present and true when the response is a replay of a prior request.
Authentication failed. Single code (invalid_api_key) covers every
sub-case: missing header, wrong scheme, malformed, unknown, revoked or
expired key. The message field disambiguates for humans debugging.
One exception: when the key could not be checked because of a server-side
fault, the status is still 401 but type is internal_error and code
is internal_server_error; retry with backoff.
Response Headers
Correlation id for this request — paste into support tickets.
Authenticated, but not allowed: insufficient_scope (the key lacks the scope in this
operation's x-scope) or agent_not_authorized (the key is limited to other agents).
Response Headers
Correlation id for this request — paste into support tickets.
not_found when the conversation isn't one of this agent's, or was deleted, or (on
getConversationMessage) the message isn't one of the conversation's; agent_not_found
when the agent is not one of your company's agents.
endpoint_not_found when an id in the path isn't a UUID.
Response Headers
Correlation id for this request — paste into support tickets.
A request with this Idempotency-Key is still running, or one with it
that was refused or failed after claiming the key (for example a
422 messaging_window_closed on sendConversationMessage) started less
than 60 seconds ago (whatever the body). Wait Retry-After seconds and
retry, or send a corrected request with a new key.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
The request body is larger than 1 MB.
Response Headers
Correlation id for this request — paste into support tickets.
Nothing was saved or sent. invalid_request_body when text is missing, empty or only
spaces, or longer than 4,096 characters (counted in UTF-16 code units, so most emoji count
as two); channel_not_supported when Mojeeb can't send on the conversation's channel;
messaging_window_closed when the customer hasn't written in the last 24 hours;
idempotency_key_in_use_with_different_params when the Idempotency-Key was used with
another body or in another conversation.
Response Headers
Correlation id for this request — paste into support tickets.
Per-key rate limit hit. Default is 60/min/key; an endpoint with an
x-rate-limit-per-minute of its own counts in a budget of its own
(today listWhatsAppTemplates, which allows 10/min/key, and
sendConversationMessage, which allows 20/min/key), and its 429
reports that limit in X-RateLimit-Limit. Retry-After tells you when to retry;
X-RateLimit-Reset is the Unix timestamp of the next window.
Per-success-response
X-RateLimit-*headers are a known gap; on 2xx responses these headers are NOT currently emitted. Customers should rely on 429 +Retry-Afterfor backoff signals.
Response Headers
Correlation id for this request — paste into support tickets.
Seconds to wait before retrying.
The per-minute request limit of the endpoint called. Every key has the same limits today.
Remaining requests in the current window. 0 on rejection.
Unix timestamp at which the current window resets.
Unexpected server-side failure. Retry with exponential backoff. If
the failure persists, send us the correlation_id.
Response Headers
Correlation id for this request — paste into support tickets.
Mojeeb couldn't check access because of a temporary fault: the key's,
or on assignLead and assignConversation the teammate's. Nothing was
changed. Retry with backoff.
Response Headers
Correlation id for this request — paste into support tickets.