Messaging & Social

Atribu is an OAuth provider for messaging as well as an attribution engine. A sibling application that needs to send a WhatsApp template, reply to an Instagram comment or read a conversation thread does it here, against the merchant's own connection, instead of registering its own Meta App.

That surface is large — WhatsApp registration, templates, broadcasts, flows, calling and health; Instagram media, triggers and conversations; email; calendar; the unified inbox — and it is documented in depth in the Node SDK reference, which carries the payload shapes, the send semantics and the webhook verification. This page is the route index and the map into it.

Where to read what

Two rules that catch every new consumer

Retrying a send safely — Idempotency-Key

A send that answers with a transport error, a 502/504 or a timeout may or may not have reached Meta. Retrying it blind can deliver the message twice. Send an Idempotency-Key header and the retry is safe:

curl -X POST https://api.atribu.app/api/v1/messages \
  -H "Authorization: Bearer atb_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f2b1c04-3a9e-4a51-9e0d-2c7b6f10a3d5" \
  -d '{"connection_id":"...","channel":"whatsapp","to":"56911112222","content":{"type":"text","text":"Hola"}}'

What each repeat does.

• Same key, first request finished, inside 24 h — the original response is replayed verbatim (same status, same provider_message_id, same sent_at) and nothing is sent.
• Same key, first request still in flight — 409 idempotency_key_in_flight. The first attempt may still deliver, so the retry is refused rather than risked. Retry the same key with backoff; once the original finishes, that key replays its response for the rest of the window.
• Same key, different body — 409 idempotency_key_conflict. Reusing one key for two different messages is a caller bug, and replaying the first message's response would silently swallow the second. Not retryable as sent: resend the original body under that key, or mint a fresh key for the new message. Everything that decides what the customer receives is compared — the channel, the connection, the recipient and the content.
• No header at all — every request sends. The header is opt-in and changes nothing for a consumer that does not use it.

The Node SDK generates a key for every mutating POST automatically. Pass your own — the one you will reuse on a retry — as idempotencyKey:

await client.messages.send(input, { idempotencyKey: message.id });
await client.conversations.sendMessage(id, { text }, { idempotencyKey: message.id });

Organic and DM attribution

/api/v1/organic/* and /api/v1/dm-ads* are the attribution reads for content that is not a paid click: organic posts and stories with their attributed outcomes, and the DM-ads cohort. GET /api/v1/profile/dark-messaging-spend estimates the revenue at risk from Instagram DM conversations that carry no attribution at all.

Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.

Next steps