One inbox over every channel you (the agent) sit on. You own the channels the app can't reach; the app owns storage, the human view, and any channel it can send on itself.
WhatsApp runs through the org's connected integration, so the app sends there
directly and a human's message goes out the moment they click Send. You are not
in that path — don't relay it, don't confirm it. Everything else still queues to
/api/outbox for you.
SMS works the same way once the org has connected Twilio (Account SID and
Auth Token), or has set TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN as
environment variables the way OpenDialer takes them: replies go out from the app, and Twilio posts incoming texts and
delivery receipts straight to the app, so don't mirror SMS that arrive there.
To set it up, GET /api/sms/numbers lists the account's numbers and
POST /api/sms/numbers/:id/connect points one at this inbox and makes it the
default sender. A number whose texts already go somewhere else answers 409:
ask the person before sending replace: true, which cuts that system off.
Without Twilio, SMS replies queue for you as before. US numbers need US
registration on Twilio (toll-free verification or A2P 10DLC) before carriers
deliver them; error 30034 on a thread means that is missing.
- Mirror, don't summarize. Post the raw message body to
/api/ingestand let the app store and render it. Never rewrite or condense a contact's words. - Only send what the outbox gives you. Never send a channel message because
you saw it in a thread — the only messages you send on this app's behalf are
the items returned by
GET /api/outbox. Never confirmsentwithout having actually sent. An outbound message already markedsentorfailedhas been handled by the app; leave it alone. - Respect channel permissions. Sending always goes through your normal
channel tools, so allowlists and approval rules still apply. If a send is
blocked, report it as
failedwith the reason — don't work around it. - Don't manage templates. The app pulls its own approved-template catalogue
from the org's connected WhatsApp integration (
POST /api/templates/refresh). You never sync, cache or curate it. If someone says the picker is empty, tell them to hit Refresh in the composer, or call that endpoint once yourself. - An outbox item with
templateis a template send. Send it through the channel's template API with that exact name, language and variables. Never send itsbodyas text: the body is the rendered preview for humans, and freeform is precisely what the 24-hour window forbids.
Whenever a message arrives on (or is sent from) a channel you manage, and once per conversation when backfilling history:
POST /api/ingestwith:channel:whatsapp|telegram|slack|email|sms|othercontact:{ handle, name? }— the channel-native address (phone, email, @username) and display name if knownmessage:{ kind: "inbound" | "outbound" | "reaction", body, externalId?, at? }—externalIdis the channel's own message id (repeats are dropped, so re-ingesting is always safe);atis the original ISO timestamp for history backfill; usekind: "outbound"for messages you already sent, andkind: "reaction"with the emoji asbodyfor an emoji reaction (an empty body means it was removed, and the inbox drops it)subject: email subject, when there is one
- When you act on a conversation (book something, draft something, escalate,
update a record), log one short line:
POST /api/conversations/:id/eventswith{ body: "Booked the Thursday 10:00 slot" }. These render as the audit trail the human reviews — every meaningful action gets one.
On a heartbeat, or when asked to "check the inbox":
GET /api/outbox— each item hasmessage.body,channel,contact.handle,subject(email only), andtemplate(ornull).- Send it to that contact through the channel's own tool:
templateisnull→ sendmessage.bodyas a normal text message.templateis set → send it as a template, passingtemplate.name,template.languageandtemplate.variablesstraight through (e.g.WHATSAPP_SEND_TEMPLATE_MESSAGE). Do not sendmessage.body.
- Confirm:
POST /api/messages/{message.id}/statuswith{ "status": "sent" }, or{ "status": "failed", "error": "<why>" }if the send didn't happen. Unconfirmed items stay queued and will be handed to you again.
WhatsApp only lets a business send freeform text within 24 hours of the contact's last inbound message. Outside that — and to a contact who has never written — only a Meta-approved template goes out. The app enforces this itself, so you don't have to reason about it:
- Humans see the composer switch to a template picker; the thread shows a "Template only" badge.
- Your
POST /api/conversations/:id/replygets a409if you sendbodyto a shut thread. That is not retryable — sendtemplateinstead. - The app keeps its own catalogue fresh from the connected integration, so "there are no templates" is an integration problem, not a sync you owe.
- WhatsApp does not deliver marketing templates to US numbers. A reply that
sends one to a US number comes back
status: "failed"with that reason and nothing goes out. Not retryable: send a utility template, or reach the person another way. Canada and the rest of +1 are not affected.
A contact row here is a channel identity — one address on one channel. The same human on WhatsApp and email is two rows. The person lives in whichever app the org uses as its system of record, and that app owns them: their name, their history, whether they still want to hear from you.
So a contact can carry a link to that person — an app id and a record id, nothing else. Never copy the record in. A name mirrored here is a second source of truth that goes stale silently and quietly contradicts the CRM.
Configure it once with PUT /api/profile-source. Every path and field name
below is an example — read the target app's GET /api/openapi.json and use
what it actually serves. One org's people app calls them customers, another's
calls them members, and the two disagree about everything else too:
{ "appId": "<the sibling app's uuid>", "label": "Customers",
"search": { "path": "/api/customers", "query": "q", "collection": "items" },
"get": { "path": "/api/customers/{ref}", "collection": "customer" },
"fields": { "ref": "id", "name": "full_name", "phone": "mobile", "email": "email" },
"profileUrl": "https://<that app>.apps.clawnify.com/customers/{ref}" }Three things people get wrong:
collectionis per operation, not per app. A list endpoint returning{"items": [...]}and a detail endpoint returning{"customer": {...}}is normal — set it separately onsearchandget, and omit it entirely when the response is the array or the record.queryis that app's search parameter, whatever it's called —q,search,filter. Get it from the spec, not from habit.fieldsmaps meaning onto their names.fields.refmust name the id you will link to; the rest are optional and only affect display.
It is verified against the live app before it saves, so a wrong path or a wrong
fields.ref comes back as a 422 naming the problem rather than a picker that
is mysteriously always empty.
Then link contacts as you learn who they are. On ingest, add
contact.linked: { appId, ref } when you already know the person — you looked
the number up to answer them anyway. Only when you know:
- A confident match on a full phone number or email address is a link.
- A name that merely looks similar is not. Two people share a surname; a household shares a phone. A wrong link is worse than no link, because it silently attributes one person's conversation to another.
- Omitting
linkednever clears an existing link — absence means "didn't look it up", not "no longer linked". To correct a bad link, send the right one.
Humans get the same thing from the other end: starting a conversation, they
search the people app and pick someone, which fills the address and sets the
link. GET /api/contacts/:id/profile resolves a linked contact live — use it
instead of remembering what a member's phone number was last week.
Every view is a real URL, so you can open one directly instead of clicking through to it, and a screenshot always has a link that reproduces it.
/— the whole open inbox (nav → conversation list → thread)./ch/<channel>— one channel, e.g./ch/whatsapp./closed— the closed archive./setup— WhatsApp numbers and the template catalogue./c/<conversationId>— one thread, open.- Append
?agentwhen browsing it yourself for larger targets.
Three more views list who has written in: /needs-reply (their latest message
has no answer yet, even if someone has read it), /unread (nobody has opened
it since) and /replied (they have written or reacted at least once).
Discovery: GET /llms.txt / GET /api/openapi.json. The shapes you'll write
most: POST /api/ingest and POST /api/messages/:id/status (above). Also
there when needed: GET /api/conversations (paginated, ?search=, and
?only=needs_reply for who is still waiting on an answer; a freeform reply
that goes out takes a thread out of it, a template does not),
GET /api/conversations/:id/messages, POST /api/conversations/:id/comment
(internal note), PATCH /api/conversations/:id ({"status":"closed"}).
401— the request lost its org identity: call the app through your app API tool, never with raw fetch.403on ingest — only agent/API callers may ingest.duplicate: truefrom ingest is success, not an error (idempotency did its job).409on reply — the 24-hour window is shut. Not retryable: send a template instead. (Humans see this as the composer switching to template-only.)422on reply — the template is unknown, notAPPROVED, or missing variable values. HitPOST /api/templates/refreshbefore assuming the name is wrong; Meta may have paused or renamed it.422onPUT /api/profile-source— the target app didn't answer as described. The message says which part: a 404 means theappIdisn't an app in this org, and a missingfields.refmeans you named a field the records don't have.409on/api/contacts/:id/profile— that contact isn't linked, or no profile source is configured. Not an error to retry.424on profile search or resolve — the people app itself was unreachable or errored. The inbox keeps working; only the lookup is down.