> ## 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 съобщение със свободен текст в рамките на активна 24-часова сесия

Този endpoint изпраща WhatsApp съобщение със свободна форма (свободен текст) до получател. За разлика от template съобщенията, съобщенията със свободна форма могат да съдържат всякакъв текст, но **изискват активен 24-часов прозорец за съобщения** — което означава, че получателят трябва да е изпратил съобщение на вашия WhatsApp изпращач в рамките на последните 24 часа.

<Warning>
  Съобщения със свободна форма могат да се изпращат само по време на активен 24-часов прозорец за съобщения. Ако сесията е изтекла, първо трябва да изпратите [template съобщение](/api-reference/whatsapp/send-template), за да започнете отново разговора. Използвайте [Session Status](/api-reference/whatsapp/session-status) endpoint, за да проверите дали сесията е активна.
</Warning>

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

### Request Body

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

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

<ParamField body="message" type="string" required>
  Съдържанието на съобщението за изпращане (максимум 4096 символа)
</ParamField>

### Response Fields

<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="session_status" type="object">
  Обновен статус на сесията след изпращане на съобщението

  <Expandable title="Свойства на статуса на сесията">
    <ResponseField name="is_open" type="boolean">
      Дали 24-часовият прозорец за съобщения е в момента отворен
    </ResponseField>

    <ResponseField name="can_send_freeform" type="boolean">
      Дали съобщения със свободна форма могат да се изпращат точно сега
    </ResponseField>

    <ResponseField name="requires_template" type="boolean">
      Дали е необходимо template съобщение
    </ResponseField>

    <ResponseField name="message" type="string">
      Четимо описание на състоянието на сесията
    </ResponseField>

    <ResponseField name="minutes_remaining" type="integer">
      Оставащи минути в 24-часовия прозорец
    </ResponseField>

    <ResponseField name="expires_at" type="string">
      ISO 8601 timestamp кога сесията изтича
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="402 Недостатъчен баланс">
  <Expandable title="Error Response">
    <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="403 Сесията е изтекла">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Съобщение, указващо че 24-часовият прозорец за съобщения е изтекъл</ResponseField>
    <ResponseField name="error_code" type="string">`SESSION_EXPIRED`</ResponseField>

    <ResponseField name="session_status" type="object">
      Текущ статус на сесията с полета `is_open`, `can_send_freeform`, `requires_template` и `message`
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="404 Не е намерен">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">`Sender not found or does not belong to you`</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_NOT_FOUND`</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="503 Изпращачът е офлайн">
  <Expandable title="Error Response">
    <ResponseField name="success" type="boolean">`false`</ResponseField>
    <ResponseField name="error" type="string">Съобщение, указващо че изпращачът в момента е офлайн</ResponseField>
    <ResponseField name="error_code" type="string">`SENDER_OFFLINE`</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://call.aiployees.com/api/user/whatsapp/send-freeform" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sender_id": 12,
      "recipient_phone": "+1234567890",
      "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://call.aiployees.com/api/user/whatsapp/send-freeform',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        sender_id: 12,
        recipient_phone: '+1234567890',
        message: 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      })
    }
  );

  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-freeform',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'sender_id': 12,
          'recipient_phone': '+1234567890',
          'message': 'Thank you for your inquiry! Our team will review your request and get back to you within 2 hours.'
      }
  )

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

<ResponseExample>
  ```json 200 Success theme={null}
  {
    "success": true,
    "conversation_id": 1234,
    "message_id": 567,
    "whatsapp_message_id": 890,
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_status": {
      "is_open": true,
      "can_send_freeform": true,
      "requires_template": false,
      "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
      "minutes_remaining": 1425,
      "expires_at": "2026-02-25T10:30:00+00:00"
    }
  }
  ```

  ```json 402 Insufficient Balance theme={null}
  {
    "success": false,
    "error": "Insufficient balance. Please top up your account.",
    "error_code": "INSUFFICIENT_BALANCE"
  }
  ```

  ```json 403 Session Expired theme={null}
  {
    "success": false,
    "error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
    "error_code": "SESSION_EXPIRED",
    "session_status": {
      "is_open": false,
      "can_send_freeform": false,
      "requires_template": true,
      "message": "Session expired. Send a template or wait for customer to reply.",
      "expired_at": "2026-02-23T10:30:00+00:00"
    }
  }
  ```

  ```json 404 Sender Not Found theme={null}
  {
    "success": false,
    "error": "Sender not found or does not belong to you",
    "error_code": "SENDER_NOT_FOUND"
  }
  ```

  ```json 422 Invalid Phone theme={null}
  {
    "success": false,
    "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
    "error_code": "INVALID_PHONE"
  }
  ```

  ```json 503 Sender Offline theme={null}
  {
    "success": false,
    "error": "Sender is not online. Current status: Offline",
    "error_code": "SENDER_OFFLINE"
  }
  ```
</ResponseExample>

### 24-часов прозорец за съобщения

WhatsApp прилага политика за **24-часов прозорец за съобщения**:

1. Когато клиент изпрати съобщение на вашия WhatsApp Business номер, се отваря 24-часов прозорец.
2. По време на този прозорец можете да изпращате съобщения със свободна форма без ограничения.
3. След като прозорецът изтече, трябва да използвате [template съобщение](/api-reference/whatsapp/send-template), за да започнете отново разговора.
4. Всяко ново съобщение от клиента нулира 24-часовия таймер.

Използвайте [Session Status](/api-reference/whatsapp/session-status) endpoint, за да проверите дали сесията е активна преди да се опитате да изпратите съобщение със свободна форма.

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

* Максималната дължина на съобщението е **4,096 символа** (ограничение на WhatsApp).
* Изпращачът трябва да е `online`. Офлайн изпращачи връщат `503` грешка.
* Разходите за съобщения се приспадат автоматично от баланса ви.
* Ограничение за заявки: 5 заявки в секунда на потребител.

***