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

# Messages

> Send SMS and WhatsApp messages, and retrieve message history across all channels.

The Messages API lets you send outbound SMS and WhatsApp messages to leads, and retrieve the full message history across all channels (SMS, WhatsApp, and email) for your workspace.

## Send an SMS

Sends an SMS message to a phone number. By default, the message is sent from your workspace's primary phone number.

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format (e.g. `"+15550001111"`).
</ParamField>

<ParamField body="body" type="string" required>
  Message content. Maximum 1,600 characters. Messages longer than 160 characters are split into segments by the carrier.
</ParamField>

<ParamField body="from_number" type="string">
  Sender phone number to use. Must be a number registered in your workspace. Defaults to your workspace's primary number.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.boltcall.org/v1/messages/sms \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15550001111",
      "body": "Thanks for calling! Your appointment is confirmed for Friday at 10am."
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/messages/sms', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: '+15550001111',
      body: 'Thanks for calling! Your appointment is confirmed for Friday at 10am.',
    }),
  });
  const message = await response.json();
  ```

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

  message = requests.post(
      'https://api.boltcall.org/v1/messages/sms',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'to': '+15550001111',
          'body': 'Thanks for calling! Your appointment is confirmed for Friday at 10am.',
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "msg_sms001",
  "channel": "sms",
  "status": "sent",
  "to": "+15550001111",
  "created_at": "2025-03-20T15:00:00Z"
}
```

***

## Send a WhatsApp message

Sends a WhatsApp message using an approved message template. Templates must be pre-approved through your WhatsApp Business Account before use.

<ParamField body="to" type="string" required>
  Recipient phone number in E.164 format.
</ParamField>

<ParamField body="template" type="string" required>
  The approved WhatsApp template name (e.g. `"appointment_reminder"`).
</ParamField>

<ParamField body="variables" type="object">
  Key-value pairs used to fill template placeholders. Keys match the variable names defined in the template.
</ParamField>

<Note>
  WhatsApp only allows outbound messages using pre-approved templates. Contact your account manager to set up templates, or manage them in **Integrations → WhatsApp**.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.boltcall.org/v1/messages/whatsapp \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+15550001111",
      "template": "appointment_reminder",
      "variables": {
        "customer_name": "Jane Smith",
        "appointment_time": "Friday at 10am"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.boltcall.org/v1/messages/whatsapp', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: '+15550001111',
      template: 'appointment_reminder',
      variables: {
        customer_name: 'Jane Smith',
        appointment_time: 'Friday at 10am',
      },
    }),
  });
  const message = await response.json();
  ```

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

  message = requests.post(
      'https://api.boltcall.org/v1/messages/whatsapp',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      json={
          'to': '+15550001111',
          'template': 'appointment_reminder',
          'variables': {
              'customer_name': 'Jane Smith',
              'appointment_time': 'Friday at 10am',
          },
      },
  ).json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "msg_wa001",
  "channel": "whatsapp",
  "status": "sent",
  "to": "+15550001111",
  "created_at": "2025-03-20T15:05:00Z"
}
```

***

## List messages

Returns paginated message history across all channels. Filter by channel or by a specific lead.

<ParamField query="channel" type="string">
  Filter by messaging channel. Accepted values: `"sms"`, `"whatsapp"`, `"email"`.
</ParamField>

<ParamField query="lead_id" type="string">
  Return only messages associated with a specific lead.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Default: `20`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.boltcall.org/v1/messages?channel=sms&limit=20" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({ channel: 'sms', limit: '20' });
  const response = await fetch(`https://api.boltcall.org/v1/messages?${params}`, {
    headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  });
  const { data, meta } = await response.json();
  ```

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

  response = requests.get(
      'https://api.boltcall.org/v1/messages',
      params={'channel': 'sms', 'limit': 20},
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
  )
  result = response.json()
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "msg_sms001",
      "channel": "sms",
      "direction": "outbound",
      "to": "+15550001111",
      "body": "Thanks for calling! Your appointment is confirmed.",
      "status": "delivered",
      "created_at": "2025-03-20T15:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 89 }
}
```

<Expandable title="Response fields">
  <ResponseField name="id" type="string">
    Unique message identifier.
  </ResponseField>

  <ResponseField name="channel" type="string">
    Messaging channel: `"sms"`, `"whatsapp"`, or `"email"`.
  </ResponseField>

  <ResponseField name="direction" type="string">
    `"outbound"` (sent by Boltcall) or `"inbound"` (received from the contact).
  </ResponseField>

  <ResponseField name="to" type="string">
    Recipient phone number or email address.
  </ResponseField>

  <ResponseField name="body" type="string">
    Message text content.
  </ResponseField>

  <ResponseField name="status" type="string">
    Delivery status: `"sent"`, `"delivered"`, or `"failed"`.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the message was created.
  </ResponseField>
</Expandable>

<Tip>
  Subscribe to the `new_lead` [webhook event](/api/webhooks) to receive real-time notifications when a new lead is captured, which includes the channel they contacted you through.
</Tip>