> ## 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 an SMS

> Start an SMS 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.

Every plan with SMS can use this endpoint.

<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 an SMS conversation in the workspace.
</ParamField>

<ParamField body="contactId" type="string">
  Start a conversation with this contact
</ParamField>

<ParamField body="phone" type="string">
  Start a conversation with this number, in E.164 format (for example `+14155551234`). 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" required>
  The text, up to 1,600 characters
</ParamField>

<ParamField body="phoneNumberId" type="string">
  Send from this number in the workspace. A reply uses the conversation's number by default. A new conversation uses the workspace's first active number.
</ParamField>

A reply to a conversation that has ended goes into a new conversation with the same contact. The response names the conversation the message went into.

## 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, or the conversation is not an SMS conversation |
| `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 text a number verified in your workspace. |
| `403` | The contact has DND on, the contact's data is restricted, or your plan does not include SMS |
| `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 Start theme={null}
  curl -X POST https://api.nedzo.ai/v1/conversations/sms \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "phone": "+14155551234",
      "name": "Jane Doe",
      "content": "Hi Jane, your appointment is confirmed for 3pm tomorrow."
    }'
  ```

  ```bash Reply theme={null}
  curl -X POST https://api.nedzo.ai/v1/conversations/sms \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "conversationId": "9b2f6c1e-3a4d-4e5f-8a9b-0c1d2e3f4a5b",
      "content": "See you then!"
    }'
  ```
</RequestExample>

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

  ```json 403 DND theme={null}
  {
    "type": "https://api.nedzo.ai/errors/forbidden",
    "title": "Forbidden",
    "status": 403,
    "detail": "Contact has Do Not Disturb (DND) on"
  }
  ```
</ResponseExample>


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