API AIMen Inbox

Ключи

Ключ организации создаёт владелец аккаунта: Настройки → API-ключи → Создать ключ. Ключ показывается один раз — сохраните его в секретах своего сервера. Ключ действует только для своей организации; отозвать его можно там же.

Передавайте ключ в заголовке каждого запроса:

Authorization: Bearer aimen_live_...

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

Успешный ответ — объект с полем data. Ошибка — объект с полем error (текст на русском, его можно показать пользователю) и HTTP-статусом:

{ "data": { ... } }
{ "error": "Шаблон не найден или ещё не одобрен" }

Лимиты

300 запросов в минуту на ключ. При превышении — 429, повторите через минуту. Контакты загружайте пачками до 100 в одном запросе, а не по одному.

Текст

curl https://inbox.aimen.kz/api/v1/messages \
  -H "Authorization: Bearer $INBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "conversationId": "8f0c…", "body": "Здравствуйте! Заказ готов к выдаче." }'

Шаблон (WhatsApp)

Первое сообщение клиенту, напоминание или ответ после 24 часов — только одобренным шаблоном.

{
  "channel": "whatsapp",
  "phone": "+77011234567",
  "templateId": "c2a1…",
  "templateParams": { "bodyParams": ["Айгерим", "15:00", "12 октября"] }
}

В существующий диалог WhatsApp — { "conversationId": "…", "templateId": "…", "templateParams": {…} }. Шаблонные сообщения Meta оплачивает отдельно, по своим тарифам.

Файлы

Разместите файл по публичной ссылке — Inbox скачает его и отправит в канал.

{
  "conversationId": "8f0c…",
  "mediaUrl": "https://example.com/files/invoice-1042.pdf",
  "mediaType": "document",
  "mediaFilename": "Счёт 1042.pdf"
}

Ответ на конкретное сообщение

replyToMessageId — id сообщения клиента из вебхука. В WhatsApp и Telegram клиент увидит цитату; в Instagram цитата видна только в Inbox.

Повторы запроса

Передайте idempotencyKey — свою уникальную строку, например id напоминания в вашей базе. Повторный запрос с тем же ключом (после таймаута) не отправит сообщение второй раз, а вернёт результат первого. Если первый ещё выполняется — 409. Если отправка не удалась, ключ освобождается и запрос можно повторить.

События

{
  "event": "message.created",
  "organizationId": "…",
  "conversationId": "…",
  "isNewConversation": true,
  "message": {
    "id": "…",
    "direction": "inbound",
    "channel": "whatsapp",
    "body": "Здравствуйте, есть размер M?",
    "createdAt": "2026-10-10T09:15:00.000Z"
  },
  "contact": { "id": "…", "name": "Айгерим", "phone": "+77011234567" }
}

{
  "event": "message.status_updated",
  "organizationId": "…",
  "conversationId": "…",
  "message": { "id": "…", "status": "delivered", "errorDetail": null }
}

Статусы: sent, delivered, read, failed (причина в errorDetail). Тестовая кнопка в Настройках присылает { "event": "ping", … }. Неизвестные события пропускайте — со временем их станет больше.

Проверка подписи

В заголовке X-Inbox-Signature — sha256= и HMAC-SHA256 тела запроса вашим секретом. Проверяйте её на каждом запросе, по сырому телу, до разбора JSON:

import crypto from "node:crypto";

export function isFromInbox(rawBody, signatureHeader, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hmac, hashlib

def is_from_inbox(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Повторы доставки

Отвечайте 2xx в течение 5 секунд, а тяжёлую обработку делайте в фоне. Если ваш сервер не ответил, событие не теряется: Inbox повторит его через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч. Событие может прийти повторно — проверяйте message.id, чтобы не обработать его дважды.

1. Организация для клиента

{ "externalId": "clinic-42", "name": "Клиника «Шипагер»" }

{ "data": { "organizationId": "…", "created": true, "apiKey": "aimen_live_…" } }

externalId — id клиента в вашей системе. Повторный вызов с тем же externalId вернёт ту же организацию с created: false и apiKey: null. Ключ организации выдаётся один раз — сохраните его сразу и дальше работайте с этим клиентом через разделы выше.

2. Виджет подключения канала

{ "organizationId": "…", "channel": "whatsapp" }

{ "data": { "embedUrl": "https://inbox.aimen.kz/embed/connect?token=…", "expiresAt": "…" } }

channel — whatsapp или instagram. Ссылка живёт 30 минут. Покажите её в iframe на странице настроек:

<iframe src="{embedUrl}" style="border:0;width:100%;height:120px" allow="popups"></iframe>

<script>
  window.addEventListener("message", (event) => {
    if (event.origin !== "https://inbox.aimen.kz") return;
    if (event.data?.type === "INBOX_CHANNEL_CONNECTED") {
      // event.data.channel: "whatsapp" | "instagram" — обновите статус через GET /api/v1/channels
    }
  });
</script>

Перед виджетом коротко объясните клиенту: откроется окно Facebook; нужен аккаунт, связанный с бизнесом; для WhatsApp — номер, на котором нет обычного приложения WhatsApp, и код из SMS; для Instagram — профессиональный аккаунт.