Отправка сообщений из вашей системы

Типичная интеграция — AI-ассистент, чат-бот, CRM или скрипт автоматизации — которой нужно отправлять исходящие сообщения через подключённые к AISAR каналы (WhatsApp, Telegram, Instagram и т.д.) и получать ответы контактов. Этот сценарий проведёт вас от токена до полного цикла «отправили → получили ответ».

Все запросы выполняются с Bearer-токеном компании (см. раздел «Аутентификация»):

Authorization: Bearer YOUR_API_TOKEN

Шаг 1 — выбрать канал

Получите список каналов компании, чтобы узнать channel_id, через который будете отправлять:

curl "https://api.aisar.app/v1/channels?status=connected" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

{
  "data": [
    {
      "id": 57,
      "name": "WhatsApp test",
      "account_name": "+77001234567",
      "status": "connected",
      "channel_type": { "id": 1, "key": "whatsapp", "name": "WhatsApp" },
      "message_operations": { "can_create": true },
      "limits": { "max_text_length": 4096 }
    }
  ]
}

Перед отправкой проверяйте status === "connected" и message_operations.can_create === true.

Шаг 2 — найти или создать контакт (опционально)

Отдельно искать или создавать контакт перед отправкой не обязательно: /messages/send сам находит диалог по получателю или создаёт новый контакт, тред и диалог. Ищите контакт заранее, только если вам нужно проверить, существует ли он, или сохранить дополнительные поля (email, теги и т.д.) до первой отправки.

curl "https://api.aisar.app/v1/contacts?search=%2B77001234567" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

curl -X POST https://api.aisar.app/v1/contacts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Иван Иванов",
    "phones": [{ "phone": "+77001234567", "type": "mobile" }]
  }'

Шаг 3 — отправить текстовое сообщение

curl -X POST https://api.aisar.app/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 57,
    "recipient": "+77001234567",
    "message_content": "Здравствуйте! Чем могу помочь?"
  }'

{
  "success": true
}

recipient — идентификатор получателя в формате, ожидаемом каналом: номер E.164 для WhatsApp/SMS, username или chat_id для Telegram Bot, IGSID для Instagram. Для отправки в группу WhatsApp передайте JID группы (<id>@g.us) — суффикс @g.us распознаётся автоматически.

Чтобы прикрепить медиа, сначала загрузите файл через POST /v1/uploads (получите media_id), затем передайте его в attachments:

curl -X POST https://api.aisar.app/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 57,
    "recipient": "+77001234567",
    "message_content": "Смотрите фото",
    "attachments": [{ "media_id": "med_01HZABCDEFGHIJKLMNOPQRSTUV" }]
  }'

Шаг 4 — отправить шаблон WhatsApp и 24-часовое окно

WhatsApp Business запрещает отправлять произвольные сообщения контакту, который не писал вам последние 24 часа — так называемое «24-часовое окно обслуживания клиента» (customer service window). Чтобы начать диалог вне этого окна или сделать рассылку, используйте одобренный Meta шаблон через /messages/send-template.

Сначала получите список одобренных шаблонов:

curl "https://api.aisar.app/v1/templates?channel_id=57&metaStatuses[]=approved" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Отправлять можно только шаблон со статусом meta_status: "approved". Затем отправьте его получателю:

curl -X POST https://api.aisar.app/v1/messages/send-template \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": 57,
    "recipient": "+77001234567",
    "template_id": 42,
    "params": { "name": "Иван", "order_id": "A-100" }
  }'

{
  "success": true,
  "message_id": 12345
}

params заполняет переменные шаблона: именованной картой ({{name}}) или по позиции — массивом либо картой с числовыми ключами ({{1}}, {{2}}). Требуется то же разрешение conversation.create; канал должен быть типа whatsapp_business.

Шаг 5 — получать входящие через вебхук

Чтобы реагировать на ответы контакта (диалоговый сценарий, например с AI-ассистентом), подпишитесь на событие message.created — см. раздел «Вебхуки». Типичный цикл: получаете message.created с direction: "inbound" → обрабатываете текст → вызываете /messages/send или /messages/send-template для ответа.

После каждой отправки (текстом или шаблоном) подписанные webhook-интеграции получают message.created с direction: "outbound", а затем message.status.updated по мере продвижения статуса доставки (sent → delivered → read, либо failed).

Когда контакт нажимает quick-reply кнопку отправленного шаблона, нажатие приходит как обычное входящее сообщение type: "text" с текстом кнопки — обрабатывайте его так же, как любой другой message.created.

Полный цикл

1. Внешняя система → GET /v1/channels
       (узнать channel_id)
2. Внешняя система → POST /v1/messages/send
       { channel_id, recipient, message_content }
3. AISAR создаёт/находит диалог, создаёт сообщение
4. AISAR → POST {webhook_url}  (event: message.created, direction: outbound)
5. Коннектор доставляет сообщение в мессенджер
6. AISAR → POST {webhook_url}  (event: message.status.updated)
7. Контакт отвечает → AISAR → POST {webhook_url}  (event: message.created, direction: inbound)
8. Внешняя система обрабатывает ответ → снова POST /v1/messages/send

Ошибки и коды ответов

Подробнее о формате ошибок — в разделе «Ошибки».