curl -X POST https://api.nedzo.ai/v1/conversations/whatsapp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactId": "456e4567-e89b-12d3-a456-426614174000",
"templateId": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
"templateVariables": { "1": "Jane" }
}'
{
"conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
"messageId": "4d1c2b3a-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
{
"type": "https://api.nedzo.ai/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "A WhatsApp template is needed outside the 24-hour window. Send templateId."
}
Conversations
Send a WhatsApp message
Start a WhatsApp conversation with a contact or phone number, or reply in one.
POST
/
conversations
/
whatsapp
curl -X POST https://api.nedzo.ai/v1/conversations/whatsapp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactId": "456e4567-e89b-12d3-a456-426614174000",
"templateId": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
"templateVariables": { "1": "Jane" }
}'
{
"conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
"messageId": "4d1c2b3a-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
{
"type": "https://api.nedzo.ai/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "A WhatsApp template is needed outside the 24-hour window. Send templateId."
}
Send
When
Sometimes the message goes out but Nedzo can’t save it. The answer is still
conversationId to reply in a conversation. Send contactId or phone to start one. Send exactly one of the three.
Plans with WhatsApp (Pro and up) can use this endpoint. On other plans it returns 403.
WhatsApp lets you send text only within 24 hours of the contact’s last message. Outside that window, send an approved template with templateId. A text send outside the window is refused with 400, and nothing is sent. See Reply windows.
Every send checks Do Not Disturb (DND) first. If the contact has DND on, or the number is on the opt-out list, the send is refused with
403 and nothing is sent. If DND can’t be checked, the send is refused too.string
Workspace UUID (required for account API keys, optional for workspace API keys)
string
Reply in this conversation. It must be a WhatsApp conversation in the workspace.
string
Start a conversation with this contact. The contact needs a phone number.
string
Start a conversation with this number, in E.164 format. Nedzo finds the contact with this number, or makes one.
string
Name for a contact this send makes. Ignored when the contact exists.
string
The text. Send
content, templateId, or both. With a template, content is the text Nedzo shows for the message in Unibox.string
An approved WhatsApp template from your workspace’s template list
object
Values for the template’s numbered placeholders, for example
{ "1": "Jane" }. Needs templateId.string
Start from this WhatsApp sender. By default Nedzo uses the workspace’s first active sender. Ignored on a reply.
When messageId is null
Sometimes the message goes out but Nedzo can’t save it. The answer is still 201, and messageId is null. The contact got the message, so don’t send it again. Then conversationId is the conversation you sent into. If that conversation had ended, the message may have gone out on a new thread that does not show in the log.
Errors
| Status | When |
|---|---|
400 | The body is not valid, the conversation is not a WhatsApp conversation, the workspace has no active WhatsApp sender, or a template is needed because the 24-hour window has closed |
402 | The account has no plan in force, no balance or messages left, the workspace hit its spend limit, or the trial has not converted. During a trial you can message a number verified in your workspace. |
403 | The contact has DND on, the contact’s data is restricted, or your plan does not include WhatsApp |
404 | The workspace, contact or conversation was not found |
409 | A send to this contact is already in progress |
429 | Too many messages in a short time. Wait, then send again. |
502 | The message could not be sent. Check the conversation before you try again, in case it went out. |
503 | Nedzo couldn’t check the workspace’s limits. Nothing was sent. Try again in a moment. |
curl -X POST https://api.nedzo.ai/v1/conversations/whatsapp \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contactId": "456e4567-e89b-12d3-a456-426614174000",
"templateId": "HXb5b62575e6e4ff6129ad7c8efe1f983e",
"templateVariables": { "1": "Jane" }
}'
{
"conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
"messageId": "4d1c2b3a-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
{
"type": "https://api.nedzo.ai/errors/validation-error",
"title": "Validation Error",
"status": 400,
"detail": "A WhatsApp template is needed outside the 24-hour window. Send templateId."
}
Was this page helpful?