xaxumessageAPI
Начало

Обзор API

Шлюз для WhatsApp, Telegram и MAX: вы подключаете номер, отправляете и получаете сообщения через один REST API, а всё, что происходит, приходит событиями на ваш вебхук.

Основные понятия

ОбъектЧто это
Клиент (tenant)Ваша организация. У клиента свой API-ключ, свои номера и свой адрес для событий. Чужие номера и переписки клиенту не видны: на любой чужой идентификатор API отвечает 404.
Номер (account)Один подключённый аккаунт мессенджера: channel = whatsapp, telegram или max. Номер привязывают по QR-коду или коду из SMS.
Чат (chat)Переписка внутри номера: личный чат с человеком, группа или канал.
Сообщение (message)Входящее или исходящее сообщение: текст, файл, геолокация, контакт, опрос… У исходящего есть статус доставки.
Файл (attachment)Вложение. Входящие файлы шлюз скачивает и хранит у себя, исходящие вы сначала загружаете, затем отправляете по attachmentId.
Событие (event)Запись «что произошло»: новое сообщение, смена статуса, номер отключился, оплата прошла… Приходят на ваш вебхук и доступны списком.

Адрес API

Все методы клиента находятся под /v1, данные — в JSON (кроме загрузки и скачивания файлов).

https://msg.xaxu.am/v1
Доступ к API открыт только с разрешённых IP-адресов. Чтобы подключить новый сервер, сообщите оператору его внешний IP.

Быстрый старт

  1. Получите API-ключ у оператора (вида xm_…). Ключ показывается один раз — сохраните его в секретах сервера. Проверка: GET /v1/me.
  2. Закажите номер — POST /v1/accounts (если оператор открыл вам самообслуживание) или попросите оператора подключить номер.
  3. Привяжите номер к телефону: GET /v1/accounts/{id}/qr — покажите QR владельцу телефона; или вход по коду из SMS.
  4. Укажите адрес для событий — PUT /v1/webhook, сохраните выданный secret: им подписано каждое событие.
  5. Отправьте сообщение — POST /v1/accounts/{id}/messages.
  6. Принимайте события message.created (новое сообщение) и message.status (доставлено, прочитано) на свой вебхук.
Первые запросы
export XM_API_KEY=xm_...            # ключ от оператора

# 1. кто я и какие у меня лимиты
curl https://msg.xaxu.am/v1/me -H "Authorization: Bearer $XM_API_KEY"

# 2. мои номера
curl https://msg.xaxu.am/v1/accounts -H "Authorization: Bearer $XM_API_KEY"

# 3. отправить текст на WhatsApp
curl -X POST https://msg.xaxu.am/v1/accounts/{accountId}/messages \
  -H "Authorization: Bearer $XM_API_KEY" -H "Content-Type: application/json" \
  -d '{"type":"text","to":{"phone":"+79991234567"},"text":"Здравствуйте!","clientId":"order-1001"}'

Разделы

АвторизацияAPI-ключ, заголовки, что делать при утечке ключа.НомераЗаказ, настройки, срок оплаты, удаление номера.Подключение номераQR-код, вход по коду, облачный пароль Telegram.Отправка сообщенийТекст, файлы, геолокация, контакт, опрос, пересылка.Чаты и историяСписок чатов, переписка, «прочитано», «печатает».ВебхукиКак приходят события и как проверить подпись.Типы событийВсе события с полями и примерами.ОшибкиФормат ошибки и все коды.