Quickstart

This page walks through the minimum viable BlueSender integration: sending a message from your CRM and receiving the reply.

Prerequisites

• A BlueSender deployment URL (https://api.bluesendr.com/ for HTTP).
• A locationId issued by the BlueSender operator. See Locations.
• A Mac running the BlueSender app, paired to a license, and bound to your locationId. See Authentication & Provisioning.

How CRMs talk to BlueSender

Your CRM integrates with BlueSender via HTTP webhooks. There is no WebSocket integration for CRMs — the WebSocket is an internal channel between the BlueSender backend and the Mac client.

• Outbound (CRM → Mac): your CRM POSTs to BlueSender's HTTP webhook. BlueSender forwards the message to the Mac client bound to the locationId.
• Inbound (Mac → CRM): the Mac forwards incoming iMessages / replies / reactions to the BlueSender backend, which delivers them to your CRM by calling its API directly: POST /conversations/messages/inbound for new inbound messages and PUT /conversations/messages/{messageId}/status for per-message status updates. See Backend → CRM delivery for the request shapes.

Send a message

curl -X POST https://api.bluesendr.com/crm/webhook/imessage \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "<your locationId>",
    "contactId": "ct_abc123",
    "messageId": "msg_001",
    "message": "Hi from CRM!",
    "phone": "+15555550100"
  }'

If a Mac is online for locationId, the message is forwarded and the HTTP response is 200 OK. When the request includes a top-level messageId, BlueSender additionally reports state back to your CRM via PUT /conversations/messages/{messageId}/status — first pending immediately after forwarding to the Mac, then a terminal delivered or failed once the Mac acts on it. If no Mac is online, the request fails immediately with HTTP 404 (body { "error": "Location not connected", ... }) — there is no backend-side queue. See HTTP Webhooks for the full body schema, signature verification, and body length limits, and the No backend queue concept for the rationale and recommended CRM-side retry pattern.

Capabilities supported today

Direction	Surface	Status
CRM → Mac, plain text + group routing + animations + voice	POST /crm/webhook	Supported
CRM → Mac, reactions (Tapbacks)	POST /crm/webhook with reaction block in metadata footer	Supported — see Reactions: Outbound
CRM → Mac, stickers	POST /crm/webhook with sticker block in metadata footer	Supported — see Stickers: Outbound
Mac → CRM, all inbound (messages, reactions, stickers, voice, animations)	Your CRM's inbound webhook	Supported

Next steps

• HTTP Webhooks — full body schema, signature verification, error responses.
• bluesendr-metadata:v1 footer — group context and structured-extension blocks for reactions / stickers (relevant for the inbound direction your CRM receives).
• Per-feature guides — group messages, reactions, stickers, voice messages, animations, rate limits.
• Errors & Codes — the error-code catalog.