MessageBird WhatsApp engine for the Axion conversation framework.
Uses the MessageBird Conversations API with AccessKey authentication.
ObjConversationWhatsapp uses the Channel360 provider. This module uses
MessageBird as the provider and follows the standard
ConversationInterface/ConversationBroker pattern.
The _EMOJI_MAP and _EMOJI_RE are imported from ObjConversationWhatsapp
— no duplication of the emoji system.
Sends messages to https://conversations.messagebird.com/v1/send using
Authorization: AccessKey {key} headers.
Inherits from ObjConversationEngine.ConversationInterface.
Config section: messagebird
| Key | Description |
|---|---|
api_key |
MessageBird API key (used in Authorization: AccessKey header) |
channel_id |
MessageBird channel ID for the WhatsApp number |
signing_key |
Signing key for HMAC-SHA256 request signature verification |
Methods:
_init_client() — loads api_key and channel_id from configtransmit_message(message, to_number="") — sends a plain-text message; applies emoji substitution; truncates at 4 096 charsdisplay_context(opts) — sends a plain-text conversation/contact/page summarydisplay_options(opts) — interactive button messages when command options exist; plain text fallback; Meta-compatible format wrapped in content.interactive; returns (first_key, first_prompt)Handles inbound MessageBird webhook events with HMAC-SHA256 signature
verification.
Methods:
verify_signature(timestamp, url, body_bytes, signature_header) — verifies the MessageBird request signature (see algorithm below); returns True on matchhandle_webhook(body) — reads body.message and body.contact; handles "text" and "interactive" (button_reply.id) types; sender from contact.msisdn; routes to ObjConversation.read_conversation() with engine "MESSAGEBIRD"run() — logs a deployment reminder; MessageBird is always webhook-driven{
"channelId": "channel-id",
"to": "+27831234567",
"type": "interactive",
"content": {
"interactive": {
"type": "button",
"body": {"text": "Choose an option"},
"action": {
"buttons": [
{"type": "reply", "reply": {"id": "1", "title": "Yes"}}
]
}
}
}
}
Maximum 3 buttons per message. Labels are truncated to 20 characters.
config.yaml:messagebird:
api_key: ""
channel_id: ""
signing_key: ""
broker.verify_signature(timestamp, url, body_bytes, sig_header)broker.handle_webhook(body)MessageBird signs each inbound request. The algorithm:
MessageBird-Request-Timestamp header value as timestampSHA256(query_string) as hexSHA256(raw_request_body) as hex"{timestamp}\n{query_sha256}\n{body_sha256}"HMAC-SHA256(signing_key, signing_string) and hex-encode the digestMessageBird-Signature header (raw hex, no prefix)This is implemented in verify_signature(). Pass the timestamp and full URL
(including query string if present) from the incoming request headers.