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

# SMS

> Send SMS messages to any phone number worldwide

SMS (Short Message Service) is the most universal messaging channel, reaching virtually any mobile phone without requiring an internet connection or app installation.

## When to Use SMS

* **Verification codes**: OTPs, 2FA
* **Transactional alerts**: Order confirmations, shipping updates
* **Time-sensitive notifications**: Appointment reminders
* **Universal reach**: When you need to reach users without smartphones

## Sending an SMS

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "+14155551234",
    text: "Your verification code is 123456",
    channel: "sms",
  });
  ```

  ```python Python theme={null}
  result = zavu.messages.send(
      to="+14155551234",
      text="Your verification code is 123456",
      channel="sms"
  )
  ```

  ```ruby Ruby theme={null}
  result = client.messages.send(
    to: "+14155551234",
    text: "Your verification code is 123456",
    channel: "sms"
  )
  ```

  ```go Go theme={null}
  result, _ := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
  	To:      zavudev.String("+14155551234"),
  	Text:    zavudev.String("Your verification code is 123456"),
  	Channel: zavudev.String("sms"),
  })
  ```

  ```php PHP theme={null}
  <?php
  $result = $client->messages->send([
      'to' => '+14155551234',
      'text' => 'Your verification code is 123456',
      'channel' => 'sms',
  ]);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+14155551234",
      "text": "Your verification code is 123456",
      "channel": "sms"
    }'
  ```
</CodeGroup>

<Tip>
  You can optionally specify a sender by passing `zavuSender` (TypeScript), `zavu_sender` (Python), or the `Zavu-Sender` header (cURL). If omitted, your project's default sender is used.
</Tip>

## Message Length

SMS messages are limited to 160 characters (GSM-7 encoding) or 70 characters (Unicode). Longer messages are split into multiple segments.

| Encoding | Single SMS | Concatenated SMS  |
| -------- | ---------- | ----------------- |
| GSM-7    | 160 chars  | 153 chars/segment |
| Unicode  | 70 chars   | 67 chars/segment  |

<Tip>
  Keep messages under 160 characters when possible to avoid multi-segment charges.
</Tip>

## Character Encoding

GSM-7 supports basic Latin characters. Using emojis, accents, or non-Latin scripts triggers Unicode encoding:

```
GSM-7:    "Your code is 123456"          (20 chars, 1 segment)
Unicode:  "Your code is 123456"         (22 chars, 1 segment with special chars)
Unicode:  "Tu codigo es 123456"           (19 chars, 1 segment, 'o' with accent triggers Unicode)
```

### GSM-7 Character Set

```
A-Z a-z 0-9
@ $ _ ! " # % & ' ( ) * + , - . / : ; < = > ?
Space, newline, carriage return
```

Any character outside this set triggers Unicode encoding.

## Sender ID

Some countries support alphanumeric sender IDs (e.g., "ZAVU" instead of a phone number).

<Warning>
  Alphanumeric sender IDs cannot receive replies. Use a phone number if you need two-way SMS.
</Warning>

### Supported Countries

| Region    | Alphanumeric Sender ID                       |
| --------- | -------------------------------------------- |
| US/Canada | Not supported (10DLC or short code required) |
| UK        | Supported                                    |
| EU        | Mostly supported                             |
| LATAM     | Varies by country                            |

## SMS Templates

Send pre-defined templates via SMS by specifying `channel: "sms"` and `messageType: "template"`:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const result = await zavu.messages.send({
    to: "+14155551234",
    channel: "sms",
    messageType: "template",
    content: {
      templateId: "tpl_abc123",
      templateVariables: {
        "1": "John",
        "2": "ORD-12345",
      },
    },
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.zavu.dev/v1/messages \
    -H "Authorization: Bearer $ZAVU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+14155551234",
      "channel": "sms",
      "messageType": "template",
      "content": {
        "templateId": "tpl_abc123",
        "templateVariables": { "1": "John", "2": "ORD-12345" }
      }
    }'
  ```
</CodeGroup>

If the template has an `smsBody`, it will be used instead of the default `body`. Contact variables like `{{contact.first_name}}` are automatically resolved from the recipient's contact metadata.

## Delivery Status

Check message status by ID:

```bash theme={null}
curl https://api.zavu.dev/v1/messages/msg_abc123 \
  -H "Authorization: Bearer zv_live_xxx"
```

| Status      | Description                |
| ----------- | -------------------------- |
| `queued`    | Accepted, pending delivery |
| `sent`      | Sent to carrier            |
| `delivered` | Confirmed delivered        |
| `failed`    | Delivery failed            |

## Common Errors

| Error Code | Description             | Solution                     |
| ---------- | ----------------------- | ---------------------------- |
| `30003`    | Unreachable destination | Invalid number or phone off  |
| `30004`    | Message blocked         | Content filtered by carrier  |
| `30005`    | Unknown destination     | Number doesn't exist         |
| `30006`    | Landline destination    | Cannot send SMS to landlines |
| `30007`    | Carrier violation       | Message rejected by carrier  |

## Compliance

<Warning>
  SMS messaging is regulated. Ensure you have consent before sending messages.
</Warning>

### Requirements

* **Opt-in consent**: Users must explicitly agree to receive SMS
* **Opt-out mechanism**: Include instructions to unsubscribe (e.g., "Reply STOP to unsubscribe")
* **Business identification**: Identify your business in the message
* **Time restrictions**: Avoid sending during quiet hours (typically 9 PM - 9 AM local time)

### Example Compliant Message

```
[YourBrand] Your order #12345 has shipped! Track: https://track.co/abc

Reply STOP to unsubscribe
```

## Best Practices

1. **Keep it short** - Aim for under 160 characters
2. **Identify yourself** - Start with your brand name
3. **Be actionable** - Include clear next steps or links
4. **Respect timing** - Send during business hours in the recipient's timezone
5. **Provide opt-out** - Always include unsubscribe instructions for marketing messages