Bridge API: авторизация, webhooks и каналы

Inbound: что приходит в webhook

Outbound: что принимает API

POST /v1/messages

Endpoint ставит outbound-сообщение в очередь. Новый запрос возвращает 202, повтор с тем же Idempotency-Key возвращает 200 и существующее сообщение.

curl -X POST https://bridge.murph.ru/v1/messages \
  -H "Authorization: Bearer brg_..." \
  -H "Idempotency-Key: 8b3f2d8c-7d8a-4e0c-9c8f-3b62d70f8b5a" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel-uuid",
    "to": { "external_id": "provider-chat-id" },
    "content": { "type": "text", "text": "Здравствуйте" }
  }'

GET /v1/messages/{id}

Endpoint возвращает outbound-сообщение в рамках проекта API key. Используйте его после 202, чтобы проверить status, providerMessageId, error, sentAt и исходный content.

curl https://bridge.murph.ru/v1/messages/message-uuid \
  -H "Authorization: Bearer brg_..."

Media outbound

content.type = media уже поддержан для telegram_qr_bridge, telegram_bot, MAX, WhatsApp и VK. Для Telegram сейчас доступны photo, video, audio, voice, animation, file; sticker для Telegram пока не включен, а voice в bot-mode может быть заблокирован самим Telegram. Для VK на prod уже подтверждены photo, video, document/file, voice и multiple attachments; audio и sticker сейчас явно не поддержаны. Размер ограничен platform setting media_max_attachment_bytes.

curl -X POST https://bridge.murph.ru/v1/messages \
  -H "Authorization: Bearer brg_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "channel-uuid",
    "to": { "external_id": "provider-chat-id" },
    "content": {
      "type": "media",
      "text": "Подпись к файлу",
      "attachments": [
        {
          "type": "photo",
          "url": "https://example.com/image.jpg",
          "filename": "image.jpg"
        }
      ]
    }
  }'

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

Подписывается raw body, а не распарсенный JSON. Timestamp нужно проверять на допустимое окно времени на стороне получателя.

signed_payload = X-Bridge-Timestamp + '.' + raw_request_body
expected = 'v1=' + hmac_sha256_hex(webhook_secret, signed_payload)
secure_compare(expected, X-Bridge-Signature)

message.inbound: reply / forwarded

В message.inbound поля message.reply_to и message.forwarded уже входят в стабильный v1 contract. Telegram и WhatsApp заполняют их best-effort, а MAX пока оставляет эти поля как reserved slots.

{
  "event_id": "event-uuid",
  "type": "message.inbound",
  "project_id": "project-uuid",
  "provider": "telegram",
  "occurred_at": "2026-04-24T10:00:00.000Z",
  "data": {
    "channel_id": "channel-uuid",
    "channel_type": "telegram_qr_bridge",
    "message": {
      "id": "123",
      "text": "Здравствуйте",
      "type": "text",
      "has_media": false,
      "date": "2026-04-24T10:00:00.000Z",
      "reply_to": null,
      "forwarded": null
    },
    "from": {
      "external_id": "telegram-user-id",
      "display_name": "Иван Петров"
    },
    "chat": {
      "external_id": "telegram-chat-id",
      "type": "private",
      "display_name": "Иван Петров"
    },
    "attachments": []
  }
}

message.interaction

message.interaction уже публикуется для WhatsApp reactions на сообщения, которые были отправлены через Bridge. Для Telegram и MAX этот event пока остается неподключенным.

{
  "event_id": "event-uuid",
  "type": "message.interaction",
  "project_id": "project-uuid",
  "provider": "whatsapp",
  "occurred_at": "2026-04-24T10:05:00.000Z",
  "data": {
    "channel_id": "channel-uuid",
    "channel_type": "whatsapp_qr_bridge",
    "message": {
      "id": "message-uuid",
      "provider_message_id": "wamid.HBgLNQ..."
    },
    "actor": {
      "external_id": "79001234567@s.whatsapp.net",
      "display_name": null
    },
    "interaction": {
      "type": "reaction",
      "action": "added",
      "key": "🔥"
    }
  }
}

message.read

message.read уже публикуется для WhatsApp read receipts и для Telegram read best-effort по raw updates. Сейчас event привязан к сообщениям, которые Bridge сам отправил во внешний канал.

{
  "event_id": "event-uuid",
  "type": "message.read",
  "project_id": "project-uuid",
  "provider": "whatsapp",
  "occurred_at": "2026-04-24T10:06:00.000Z",
  "data": {
    "channel_id": "channel-uuid",
    "channel_type": "whatsapp_qr_bridge",
    "message": {
      "id": "message-uuid",
      "provider_message_id": "wamid.HBgLNQ..."
    },
    "reader": {
      "external_id": "79001234567@s.whatsapp.net",
      "display_name": null
    },
    "read": {
      "read_at": "2026-04-24T10:06:00.000Z"
    }
  }
}

message.deleted

message.deleted уже публикуется для WhatsApp revoke/delete. Bridge best-effort находит исходное сообщение по provider_message_id, поэтому в data.message.id может прийти внутренний Bridge id удаленного сообщения.

{
  "event_id": "event-uuid",
  "type": "message.deleted",
  "project_id": "project-uuid",
  "provider": "whatsapp",
  "occurred_at": "2026-04-29T08:10:00.000Z",
  "data": {
    "channel_id": "channel-uuid",
    "channel_type": "whatsapp_qr_bridge",
    "message": {
      "id": "bridge-message-uuid",
      "provider_message_id": "AC481C91312A67417E4EC4733127442E"
    },
    "actor": {
      "external_id": null,
      "display_name": null
    },
    "deleted": {
      "deleted_at": "2026-04-29T08:10:00.000Z",
      "scope": "for_everyone",
      "direction": "outbound"
    }
  }
}