> ## 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.

# Изпращане на SMS

> Изпратете SMS съобщение, използвайки вашия телефонен номер

Този endpoint ви позволява да изпращате SMS съобщения, използвайки закупените от вас телефонни номера. SMS-ът ще бъде изпратен чрез Twilio и разходите ще бъдат автоматично приспаднати от баланса на вашия акаунт.

### Request Body

<ParamField body="from" type="integer" required>
  ID-то на вашия телефонен номер, от който да изпратите SMS-а (трябва да поддържа SMS)
</ParamField>

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

<ParamField body="body" type="string" required>
  Съдържанието на SMS съобщението (макс. 300 знака)
</ParamField>

### Response

<ResponseField name="message" type="string">
  Съобщение за успех, потвърждаващо че SMS-ът е изпратен
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="integer">
      Уникалният идентификатор на SMS записа
    </ResponseField>

    <ResponseField name="phone_number_id" type="integer">
      ID-то на телефонния номер, използван за изпращане на SMS-а
    </ResponseField>

    <ResponseField name="to" type="string">
      Телефонният номер на получателя в E.164 формат
    </ResponseField>

    <ResponseField name="body" type="string">
      Съдържанието на SMS съобщението
    </ResponseField>

    <ResponseField name="user_id" type="integer">
      ID-то на потребителя, който е изпратил SMS-а
    </ResponseField>

    <ResponseField name="segments" type="integer">
      Брой SMS сегменти (за целите на таксуването)
    </ResponseField>

    <ResponseField name="segment_price" type="number">
      Цена за SMS сегмент
    </ResponseField>

    <ResponseField name="total_cost" type="number">
      Обща цена на SMS-а (segment\_price \* segments)
    </ResponseField>

    <ResponseField name="status" type="string">
      Текущото състояние на SMS-а
    </ResponseField>

    <ResponseField name="sms_sid" type="string">
      Twilio SMS SID за проследяване
    </ResponseField>

    <ResponseField name="created_at" type="string">
      Датата и часът, когато е създаден SMS-ът
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      Датата и часът, когато SMS-ът е актуализиран за последно
    </ResponseField>
  </Expandable>
</ResponseField>

### Грешни Отговори

<ResponseField name="400 Bad Request">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Съобщение за грешка, описващо проблема (невалиден телефонен номер, недостатъчен баланс и т.н.)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="500 Internal Server Error">
  <Expandable title="Error Response">
    <ResponseField name="message" type="string">
      Съобщение за грешка, указващо неуспешно изпращане на SMS
    </ResponseField>

    <ResponseField name="error" type="string">
      Детайлна информация за грешката
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 Success Response theme={null}
  {
    "message": "SMS sent successfully",
    "data": {
      "id": 456,
      "phone_number_id": 78,
      "to": "+1234567890",
      "body": "Hello! This is a test message from Your Company. How can we help you today?",
      "user_id": 1,
      "segments": 1,
      "segment_price": 0.0075,
      "total_cost": 0.0075,
      "status": "sent",
      "sms_sid": "SM1234567890abcdef1234567890abcdef",
      "created_at": "2025-08-04 15:30:00",
      "updated_at": "2025-08-04 15:30:02"
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "From number not found"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Invalid to phone number"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "Insufficient balance"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "message": "From number is not SMS capable"
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "message": "Failed to send SMS",
    "error": "Twilio API error details"
  }
  ```
</ResponseExample>

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

* Телефонният номер на подателя трябва да принадлежи на удостоверения потребител
* Телефонният номер на подателя трябва да поддържа SMS
* Абонаментът за телефонния номер трябва да бъде активен (не изтекъл)
* Необходим е достатъчен баланс по акаунта за покриване на разходите за SMS
* Телефонните номера се форматират автоматично в E.164 формат
* Разходите за SMS варират според държавата на получателя и се таксуват за сегмент
* Дълги съобщения могат да бъдат разделени на няколко сегмента, увеличавайки цената
* Телефонният номер на получателя трябва да бъде валиден според международните стандарти