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

# SMS Messaging

> Send and manage SMS messages with templates, encoding, and delivery tracking

## Message Lifecycle

Messages progress through these states:

| Status      | Description              |
| ----------- | ------------------------ |
| `pending`   | Created, awaiting queue  |
| `queued`    | In queue for submission  |
| `submitted` | Sent to carrier          |
| `delivered` | Confirmed delivery       |
| `failed`    | Delivery failed          |
| `expired`   | Validity period exceeded |

## Templates & Variables

Use templates for dynamic content:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/messages \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "destination": "+1234567890",
      "template_id": "tmpl_abc123",
      "variables": {
        "VAR1": "John",
        "VAR2": "12345"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api-message.nativehub.live/api/v1/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      destination: '+1234567890',
      template_id: 'tmpl_abc123',
      variables: {
        VAR1: 'John',
        VAR2: '12345'
      }
    })
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api-message.nativehub.live/api/v1/messages',
      headers={
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
      },
      json={
          'destination': '+1234567890',
          'template_id': 'tmpl_abc123',
          'variables': {
              'VAR1': 'John',
              'VAR2': '12345'
          }
      }
  )
  data = response.json()
  ```
</CodeGroup>

Template format: `Hello {{VAR1}}, your code is {{VAR2}}`

## Message Encoding

### GSM-7 (Default)

* **160 characters** per message
* **153 characters** per part for multipart
* Standard Latin characters

### UCS-2/Unicode

* **70 characters** per message
* **67 characters** per part for multipart
* Used for emojis, non-Latin scripts

<Info>
  Encoding is auto-detected. A single emoji triggers Unicode encoding for the entire message.
</Info>

## DNC (Do-Not-Call) Check

Messages to numbers on the DNC list are automatically rejected before sending.

<CodeGroup>
  ```bash Check DNC Status theme={null}
  curl https://api-message.nativehub.live/api/v1/dnc/check/+1234567890 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Add to DNC theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/dnc \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"phone": "+1234567890"}'
  ```
</CodeGroup>

## Priority Levels

Control sending order:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/messages \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "destination": "+1234567890",
      "content": "Urgent notification",
      "priority": "high"
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch('https://api-message.nativehub.live/api/v1/messages', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      destination: '+1234567890',
      content: 'Urgent notification',
      priority: 'high'
    })
  });
  ```

  ```python Python theme={null}
  requests.post(
      'https://api-message.nativehub.live/api/v1/messages',
      headers={'Authorization': 'Bearer YOUR_TOKEN'},
      json={
          'destination': '+1234567890',
          'content': 'Urgent notification',
          'priority': 'high'
      }
  )
  ```
</CodeGroup>

Priority values: `low`, `normal` (default), `high`

## Delivery Logs

Track message delivery attempts:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api-message.nativehub.live/api/v1/messages/msg_abc123/logs \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api-message.nativehub.live/api/v1/messages/msg_abc123/logs',
    {
      headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
    }
  );
  const logs = await response.json();
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api-message.nativehub.live/api/v1/messages/msg_abc123/logs',
      headers={'Authorization': 'Bearer YOUR_TOKEN'}
  )
  logs = response.json()
  ```
</CodeGroup>

Response format:

```json theme={null}
{
  "data": [
    {
      "timestamp": "2026-02-14T10:30:00Z",
      "status": "submitted",
      "provider": "twilio"
    },
    {
      "timestamp": "2026-02-14T10:30:15Z",
      "status": "delivered",
      "error_code": null
    }
  ]
}
```

## Hold & Release

Pause and resume message queues:

<CodeGroup>
  ```bash Hold Message theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/messages/msg_abc123/hold \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Release Message theme={null}
  curl -X POST https://api-message.nativehub.live/api/v1/messages/msg_abc123/release \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

<Warning>
  Held messages remain in `pending` status until released. They do not expire while held.
</Warning>