App links
How a profile's owner lets a consumer app act as a read-only guest on an existing profile, and the two routes the app uses to read and leave its links.
This page is for a consumer application (Vitrina is the reference one) that works for a business whose Atribu profile already exists — usually one an agency built — instead of provisioning a new profile for it.
What a link is
A link is the profile owner's decision: "app X may act as a guest on my profile
P, which X knows as its own tenant R". R is your external_ref.
- Only the owner creates a link. Today an Atribu operator records it on the owner's written instruction, and the workspace owner gets a confirmation email that lists every linked profile. There is no API that lets an app create, re-activate or widen a link.
- The profile stays the owner's. A link never makes your app the profile's provisioner. The owner's connections, Conversion Sync rules, destinations, stage mapping, plan and members do not change.
- One link per tenant, one per profile. An
external_refhas at most one active link for your app, and a profile has at most one active link to your app.
What your app can do on a linked profile
A link gives your app ONE grant on the profile, capped at the link's
scope_ceiling. Mint its key the usual way: POST /oauth/token with
grant_type=client_credentials and the linked profile_id.
| Connect scope | What the key can do |
|---|---|
linked_read (always) | Read the profile's connections, numbers, campaigns and conversions (connections:read, analytics:read, campaigns:read, conversions:read, realtime:read). Read-only, and never person-level: no customers:read, no visitors:read. |
linked_outcomes | Report outcomes with POST /api/v1/events (events:write), and only these event names: appointment_booked, appointment_attended, payment_received, first_payment, returning_first_payment, deposit_paid, closed_won, appointment_no_show, appointment_cancelled, closed_lost, disqualified. |
ads_billing | Read ad spend for billing (GET /api/v1/partner/ads/billing). |
The link's flags decide what you receive:
feeds_outcomes: the profile'soutcome.recordedevents reach your app from the link's activation on, by webhook and byGET /api/v1/outcomes/recorded. Withhistory=truethat route also serves up to 12 months of the profile's GoHighLevel outcomes from before the link, once and on request. History items carrydata.history: true, and the last page hasmeta.history.complete: true.share_contact: those events carry the person's name, phone and email. It is off unless the owner recorded a legal basis for it.reports_outcomes: mirrorslinked_outcomesinscope_ceiling.
What it cannot do. A guest key cannot connect, disconnect, sync or finalize
the owner's Meta, Google or GoHighLevel accounts. It cannot create datasets,
pixels, destinations or Conversion Sync rules, cannot change the stage mapping,
the entitlement or the members, and cannot retract events. The routes
/api/v1/payments/webpay, /api/v1/partner/declared-source,
/api/v1/partner/ad-referrals and /api/v1/partner/wa-joins refuse it.
These refusals answer 403 with a message that starts with
linked_profile_owner_managed.
WhatsApp on a linked profile
A link always lets your app connect the business's own WhatsApp number on the
linked profile, through the same consent you use today: /oauth/authorize with
scope=whatsapp and your signed id_token_hint naming your tenant
(external_ref). For a tenant with an active link, the consent lands on the
linked profile, even if you also provisioned a profile for that tenant; the
link wins. Embedded Signup, coexistence (wa_connect_mode=coexistence) and
WABA-only sharing (wa_connect_mode=only_waba_sharing) all work there.
- It is your number on that profile. The connection carries your app's
connection grant from the moment it is created, the code exchange gives you
its key, and your webhook subscription on the profile receives its
message.*events andconnection.connected. - It never creates anything at Meta. Connecting it never creates a WhatsApp dataset or a Conversion Sync destination. The profile's owner decides that. Its outcomes count in the owner's existing Conversion Sync rules, like the rest of the profile's outcomes.
- It ends with the link. Whoever ends the link, the number ends too: its token is wiped and its conversation history is kept.
- Only WhatsApp. Any other scope for a linked tenant (
instagram,messenger,tiktok_messaging,email,calendar,calendar_read, and the connectionless scopes) is refused, and is never re-routed to a profile you provisioned. - Refusals reach your callback. Every refusal below that happens on
Atribu's connect page (after the person finished Meta's dialog) is an error
redirect to your
redirect_uri, with yourstate, exactly like a consent refusal:?error=access_denied&error_description=whatsapp_owned_by_profile_owner(orwhatsapp_dataset_owned_by_profile_owner),?error=invalid_request&error_description=external_ref_link_revoked, or?error=temporarily_unavailable&error_description=app_profile_link_lookup_failed. No code is issued; start the connect again once the cause is fixed. - The owner's own number is never taken over. If the same WhatsApp account
is live on the profile as the owner's connection, the connect answers
409(whatsapp_owned_by_profile_owner). If the owner's connection for it has ended, your connect takes it over as yours, and nothing the reconnect replays is exported to Meta. One exception answers409(whatsapp_dataset_owned_by_profile_owner): the owner already has an enabled Meta dataset for that number, which would start sending again.
The consent answers with OAuth error redirects to your redirect_uri, with
your state replayed:
error | error_description | What happened |
|---|---|---|
invalid_request | scope_not_allowed_on_linked_profile | The tenant is linked and the scope is not whatsapp. |
invalid_request | external_ref_link_revoked | The tenant's link was revoked. It connects nowhere until the owner links it again or you provision it again. |
temporarily_unavailable | app_profile_link_lookup_failed | Atribu could not read the link. Retry. |
When the link cannot be read even after one retry, a tenant this Atribu process
saw as NOT linked within the last 60 seconds still reaches the profile you
provisioned for it. The window cuts both ways: a tenant linked within those
60 seconds, while the link read keeps failing and a profile you provisioned for
the same ref exists, can land on that provisioned profile. If that happens to a
WhatsApp connect, Atribu moves the number to the linked profile (the move
below); you get the same connection.revoked / connection.connected pair.
If the link is revoked while the person is inside Meta's dialog, the same
invalid_request / external_ref_link_revoked pair comes back from the
connect page (HTTP 403), and POST /oauth/token refuses the code with
invalid_grant / external_ref_link_revoked. Nothing stays connected. If the
token endpoint cannot read the link, it answers server_error /
app_profile_link_lookup_failed (the token endpoint's own error vocabulary):
retry the exchange while the code is valid.
A number moved onto a linked profile
When a business's number is already live on a profile your app provisioned and
the owner links your tenant to their own profile, Atribu can move the number
there instead of asking the business to connect it again. The move keeps it
yours, with your grant on the new connection, and the replayed history is never
exported to the owner's Meta destinations. Your subscriptions receive two
events that share data.external_account_id (the WABA id):
{
"type": "connection.revoked",
"provider": "atribu",
"connection_id": "<old connection id>",
"data": {
"provider": "whatsapp",
"external_account_id": "<waba id>",
"reason": "moved_to_another_profile",
"moved_to_connection_id": "<new connection id>"
}
}{
"type": "connection.connected",
"provider": "atribu",
"connection_id": "<new connection id>",
"data": {
"provider": "whatsapp",
"external_account_id": "<waba id>",
"external_account_name": "…",
"reconnected": false,
"moved_from_connection_id": "<old connection id>"
}
}moved_to_connection_id and moved_from_connection_id name each other, so
either half alone is enough to pair them; data.external_account_id matches
too. Both are enqueued durably and retried for up to 24 hours, after the
source connection is already ended, so the revoke can arrive after its token
is gone: do not call the old connection to confirm it.
Before Atribu runs the move, your app's ACTIVE webhook subscriptions on the linked profile must cover every pair below: one subscription has to list both the provider and the event type, because that is how events are matched when they are queued. Anything queued before then is never sent to you, so the move is refused until all six are covered:
providers | events |
|---|---|
atribu | connection.connected, connection.revoked |
whatsapp | message.received, message.echo, message.history, message.delivery |
Treat the pair as a re-bind, not a disconnect: point your record of the number
at the new connection_id and the linked profile_id, then mint its key with
POST /oauth/token, grant_type=client_credentials, the linked profile_id
and connection_id=<new connection id>. The last 30 days of the number's
messages are replayed onto the new connection marked replayed: true. You
already hold them, so de-duplicate on the message id.
Avoiding duplicate conversions
An outcome your app reports with POST /api/v1/events (for example
appointment_booked from the clinic's scheduling software) and the same
outcome that the owner's CRM stage mapping produces (a GoHighLevel stage
"Agendado") are two separate records in Atribu. Each has its own event id, so
the owner's Conversion Sync rules send both, and Meta receives two events for
one appointment.
Atribu collapses them only when both conditions hold:
- the owner's rule has
cross_rule_dedup: truein itssource_config. A later event with the same platform event name, on the same destination, for the same person, withincross_rule_dedup_days(1 to 180, default 30), is not sent and readsskippedwithskip_reason: cross_rule_duplicate. It is off unless the rule sets it, and only the owner can set it; - both records resolve to the same person, for example the same phone number on the CRM contact and on your event.
Click-to-WhatsApp sales are also limited to one Purchase or OrderCreated per
click and per sale. A sale is identified by its order id or its GoHighLevel
opportunity. A payment you report without either one counts as a different
sale.
Read your links
GET /api/v1/app-links?external_ref={your tenant id}Authenticate with your app's own client_id and client_secret (HTTP Basic),
the same credential as POST /api/v1/profiles. The route only ever returns your
app's links. Filters: external_ref, status (active or revoked) and
limit (default 100, maximum 500). Links come newest first, and has_more
says when there are more.
{
"data": {
"links": [
{
"link_id": "…",
"external_ref": "tenant_8f2c",
"tenant_label": "Clínica Norte",
"profile_id": "…",
"workspace_id": "…",
"status": "active",
"flags": { "share_contact": true, "feeds_outcomes": true, "reports_outcomes": true },
"scope_ceiling": ["linked_read", "linked_outcomes"],
"activated_at": "2026-11-14T12:00:00.000Z",
"revoked_at": null,
"revoked_via": null
}
],
"has_more": false
}
}revoked_via says who ended a link: owner, app, operator (on the
owner's instruction) or profile_archived.
Leave a link
DELETE /api/v1/app-links/{id}One call ends everything the link gave your app on that profile:
- the link itself;
- every grant your app holds on the profile, and every key minted under them;
- your webhook subscriptions on the profile, which are paused;
- every messaging connection your app connected there, which ends with its token wiped and its conversation history kept.
The owner's own connections, rules and data are not touched, and the workspace
owner is told by email. The call is idempotent: ending a link that has already
ended answers 200 with revoked: false. The response carries app_link,
revoked, keys_revoked, subscriptions_paused and connections_ended.
To link the profile again, the owner has to approve it again.
How the owner sees and revokes it
In the Atribu console, Settings → Who can read my data lists your app on
each linked profile with the tenant label, the flags and the date it was linked.
Revoke ends the link with the same teardown as your DELETE. The same
listing is GET /api/v1/workspaces/{workspaceId}/connected-apps, where a
linked grant carries app_link. A profile's
readiness also lists its links in linked_apps.
Archiving the profile ends its links too.
When your key starts answering 401, call GET /api/v1/app-links?external_ref=….
A revoked status means the owner ended the link: stop syncing that tenant,
and do not re-provision it on your own.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/app-links | List the profile links owners gave your app (app-authenticated) |
DELETE | /api/v1/app-links/{id} | End one of your app's profile links (app-authenticated) |
Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.