> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a WhatsApp message

> Start a WhatsApp conversation with a contact or phone number, or reply in one.

Send `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](/integrations/whatsapp#reply-windows).

<Warning>
  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.
</Warning>

<ParamField body="workspaceId" type="string">
  Workspace UUID (required for account API keys, optional for workspace API keys)
</ParamField>

<ParamField body="conversationId" type="string">
  Reply in this conversation. It must be a WhatsApp conversation in the workspace.
</ParamField>

<ParamField body="contactId" type="string">
  Start a conversation with this contact. The contact needs a phone number.
</ParamField>

<ParamField body="phone" type="string">
  Start a conversation with this number, in E.164 format. Nedzo finds the contact with this number, or makes one.
</ParamField>

<ParamField body="name" type="string">
  Name for a contact this send makes. Ignored when the contact exists.
</ParamField>

<ParamField body="content" type="string">
  The text. Send `content`, `templateId`, or both. With a template, `content` is the text Nedzo shows for the message in Unibox.
</ParamField>

<ParamField body="templateId" type="string">
  An approved WhatsApp template from your workspace's template list
</ParamField>

<ParamField body="templateVariables" type="object">
  Values for the template's numbered placeholders, for example `{ "1": "Jane" }`. Needs `templateId`.
</ParamField>

<ParamField body="whatsappSenderId" type="string">
  Start from this WhatsApp sender. By default Nedzo uses the workspace's first active sender. Ignored on a reply.
</ParamField>

## 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. |

<RequestExample>
  ```bash Template theme={null}
  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" }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
    "messageId": "4d1c2b3a-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
  }
  ```

  ```json 400 Template needed theme={null}
  {
    "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."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.