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

# Send SMS

> Send a text message from the agent's SMS number

Queues one text message from the agent's hosted SMS number. The message joins that contact's conversation, so when the customer texts back, the agent answers the reply like any other inbound text.

The agent needs an enabled SMS number (a hosted SMS channel). Agents without one get `409 sms_not_enabled`.

Account, reseller, organization and [agent-scoped](https://docs.telzino.com/api-reference/authentication.md#agent-scoped-api-keys) API keys can all call this endpoint. An agent-scoped key can only send from its own agent.

## Path Parameters

**agentId** `string` *required*

The agent that sends the text (UUID)

## Headers

**Idempotency-Key** `string`

Optional, up to 200 characters. Retrying with the same key returns the first message (`200`) instead of sending a second text. Use your own id for the event, for example `order-9312-ready`.

## Request Body

**to** `string` *required*

Recipient in E.164 format, e.g. `+15551234567`

**body** `string` *required*

The text, 1 to 1600 characters. Leading and trailing spaces are removed.

**from** `string`

One of the agent's SMS numbers, in E.164. Defaults to the agent's first SMS number.

```bash cURL theme={null}
curl -X POST https://api.telzino.com/v1/agents/3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f/sms \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Idempotency-Key: order-9312-ready" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+15551234567", "body": "Your order is ready for pickup." }'
```

```ts @telzino/server theme={null}
await telzino.sms.send({
  agentId: '3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f',
  to: '+15551234567',
  body: 'Your order is ready for pickup.',
  idempotencyKey: 'order-9312-ready',
});
```

```json 202 theme={null}
{
  "id": "6d0c8b8e-2f2a-4a8e-9b1c-5f3e2d1a0b9c",
  "status": "queued",
  "to": "+15551234567",
  "from": "+15550000001",
  "agent_id": "3f1c2a4e-8b7d-4c3a-9e2f-1a2b3c4d5e6f"
}
```

```json 409 theme={null}
{
  "error": "opted_out",
  "error_description": "The recipient replied STOP to this number."
}
```

## Response

**id** `string`

The message id

**status** `string`

Always `queued`. Telzino sends the text within a few seconds.

**from** `string`

The agent number it is sent from

`202` means the text is queued. A repeat with the same `Idempotency-Key` answers `200` with the first message.

## Errors

| Status | `error` | Meaning |
| - | - | - |
| 400 | `invalid_request` | `to` or `from` is not E.164, or `body` is empty or too long. |
| 403 | `insufficient_scope` | The key cannot call this endpoint. |
| 404 | `not_found` | No such agent, or it is outside the key's scope. |
| 409 | `sms_not_enabled` | The agent has no enabled SMS number (or `from` is not one of them). |
| 409 | `opted_out` | The recipient texted STOP to this number. Nothing is sent. |
| 429 | `rate_limited` | More than 60 texts in a minute from this agent. |
| 503 | `temporarily_unavailable` | Retry shortly. With an `Idempotency-Key` a retry never sends twice. |

> [!NOTE]
>
> Only send to people who agreed to receive texts from you. A recipient who replies STOP is opted out of that number, and later sends to them answer `409 opted_out`.


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