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

# Изпращане на шаблонно съобщение

> Изпращане на WhatsApp съобщение чрез одобрен шаблон

Този endpoint изпраща WhatsApp съобщение чрез предварително одобрен шаблон. Шаблонните съобщения са задължителни при започване на разговор с потребител за първи път или при изпращане на съобщения извън 24-часовия прозорец за съобщения.

<Note>
  Този endpoint има ограничение от **5 заявки в секунда** на потребител.
</Note>

### Тяло на заявката

<ParamField body="sender_id" type="integer" required>
  ID на WhatsApp изпращача от който да се изпрати (получен от endpoint-а [Get Senders](/api-reference/whatsapp/get-senders))
</ParamField>

<ParamField body="template_id" type="integer" required>
  ID на шаблона за съобщение който да се използва (получен от endpoint-а [Get Templates](/api-reference/whatsapp/get-templates))
</ParamField>

<ParamField body="recipient_phone" type="string" required>
  Телефонния номер на получателя в международен формат (например, `+1234567890`)
</ParamField>

<ParamField body="recipient_name" type="string">
  Името на получателя, максимум 255 символа (използва се за проследяване на разговори и CRM цели)
</ParamField>

<ParamField body="variables" type="object">
  Двойки ключ-стойност за променливите на шаблона. Ключовете трябва да съответстват на имената на променливите от шаблона. Ако шаблонът има променливи `{{1}}`, `{{2}}`, и т.н., подайте ги като `{"1": "стойност1", "2": "стойност2"}` или използвайте именуваните ключове от масива `variables` на шаблона.

  <Expandable title="Примерни променливи">
    <ParamField body="1" type="string">
      Стойност за първата променлива на шаблона
    </ParamField>

    <ParamField body="2" type="string">
      Стойност за втората променлива на шаблона
    </ParamField>
  </Expandable>
</ParamField>

### Полета в отговора

<ResponseField name="success" type="boolean">
  Дали съобщението е изпратено успешно
</ResponseField>

<ResponseField name="conversation_id" type="integer">
  ID на разговора (нов или съществуващ) свързан с това съобщение
</ResponseField>

<ResponseField name="message_id" type="integer">
  ID на записа на съобщението в разговора
</ResponseField>

<ResponseField name="whatsapp_message_id" type="integer">
  ID на записа на WhatsApp съобщението
</ResponseField>

<ResponseField name="message_sid" type="string">
  Twilio message SID за проследяване на доставката
</ResponseField>

<ResponseField name="status" type="string">
  Началният статус на доставка на съобщението (например, `queued`, `sent`)
</ResponseField>

### Отговори при грешки

<ResponseField name="402 Insufficient Balance">
  <Expandable title="Отговор при грешка">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Insufficient balance. Please top up your account.`</ResponseField>
    <ResponseField name="error_code" type="string">`INSUFFICIENT_BALANCE`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Not Found">
  <Expandable title="Отговор при грешка">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you` или `Template not found or does not belong to this sender`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND` или `TEMPLATE_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="422 Unprocessable Entity">
  <Expandable title="Отговор при грешка">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Подробно съобщение за грешката</ResponseField>

    <ResponseField name="error_code" type="string">
      Един от: `SENDER_OFFLINE`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_NOT_SYNCED`, `TEMPLATE_MISMATCH`, `NO_ASSISTANT_CONFIGURED`, `INVALID_PHONE`, `MESSAGING_LIMIT_UNAVAILABLE`, `VOICE_CALL_LIMIT_NOT_MET`, `TWILIO_ERROR_{code}`, `UNKNOWN_ERROR`
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://call.aiployees.com/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 45,
      "recipient_phone": "+1234567890",
      "recipient_name": "John Doe",
      "variables": {
        "1": "John",
        "2": "January 15, 2026",
        "3": "2:00 PM"
      }
    }'
  ```

  ```bash Шаблон без променливи theme={null}
  curl -X POST "https://call.aiployees.com/api/user/whatsapp/send" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "template_id": 46,
      "recipient_phone": "+1234567890"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://call.aiployees.com/api/user/whatsapp/send',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        template_id: 45,
        recipient_phone: '+1234567890',
        recipient_name: 'John Doe',
        variables: {
          '1': 'John',
          '2': 'January 15, 2026',
          '3': '2:00 PM'
        }
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```

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

  response = requests.post(
      'https://call.aiployees.com/api/user/whatsapp/send',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'template_id': 45,
          'recipient_phone': '+1234567890',
          'recipient_name': 'John Doe',
          'variables': {
              '1': 'John',
              '2': 'January 15, 2026',
              '3': '2:00 PM'
          }
      }
  )

  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Успех theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "queued"
  }
  ```

  ```json 402 Недостатъчен баланс theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 404 Изпращачът не е намерен theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 404 Шаблонът не е намерен theme={null}
  {
    "success": false,
    "error": "Template not found or does not belong to this sender",
    "error_code": "TEMPLATE_NOT_FOUND"
  }
  ```

  ```json 422 Шаблонът не е одобрен theme={null}
  {
    "success": false,
    "error": "Template is not approved. Current status: pending",
    "error_code": "TEMPLATE_NOT_APPROVED"
  }
  ```

  ```json 422 Невалиден телефон theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 422 Изпращачът е офлайн theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### Забележки

* Шаблонните съобщения трябва да използват **одобрени** шаблони. Шаблони със статус `pending` или `rejected` ще се провалят.
* Изпращачът трябва да е `online`. Офлайн изпращачи не могат да изпращат съобщения.
* Разходите за съобщения се приспадат автоматично от баланса на акаунта ви (кредити за tenant потребители, минути за директни потребители).
* След изпращане на шаблонно съобщение се отваря 24-часов прозорец за съобщения. През този прозорец можете да изпращате [свободни съобщения](/api-reference/whatsapp/send-freeform) без нужда от шаблон.
* Ако разговор със получателя вече съществува, съобщението се добавя към съществуващия разговор.
* Ограничение на честотата: 5 заявки в секунда на потребител.

***