Percorso dell'integratore: attivazione e webhook 100 % via API

GET /v1/onboarding-links/{id}

Se attivi i tuoi clienti dal tuo sistema, senza entrare nel pannello, questo è il percorso completo, in cinque passi.

1. Un link per cliente. POST /v1/onboarding-links con il tuo externalId (il tuo id per quel cliente) e webhook: { url }. Ti restituiamo l'url per il tuo cliente e il segreto whsec_… del webhook una sola volta: salvalo subito, firma tutto ciò che riguarda quel cliente. Un externalId già usato da un altro numero del tuo account dà 409 in questo momento, non alla fine dell'attivazione.

2. Il tuo cliente si collega. Apre l'url, entra con il suo account Meta e sceglie il numero. Alla fine, il numero nasce con il suo webhook (l'URL del link) e lì arriva onboarding.completed, con connection.id (conn_…), il tuo externalId, reconnected e il webhookId. Un numero nuovo porta anche connection.created, come sempre.

3. Se non finisce, lo sai lo stesso. Ogni tentativo interrotto (fallito, annullato o abbandonato) manda onboarding.failed all'URL del webhook del link, firmato con lo stesso segreto: reason (meta_error, incomplete, timeout, cancelled, abandoned…), metaErrorCode e metaMessage se Meta li ha dati, e linkUsable (se il tuo cliente può riprovare con lo stesso link). Se preferisci chiedere: GET /v1/onboarding-links?externalId=… o GET /v1/onboarding-links/{id} restituiscono outcome (pending, completed o failed, con lo stesso motivo).

4. Il webhook del numero è tuo. Lo vedi e lo modifichi con /v1/webhooks?externalId=…: URL, eventi, intestazione fissa, ruotare il segreto, provarlo.

5. La disattivazione. Quando il numero si scollega (dal pannello, perché l'azienda ci ha tolto l'accesso su Meta o perché il permesso è stato revocato), il suo webhook viene spento (active: false, disabledReason: "connection_disconnected") e smette di ricevere. Se si ricollega lo stesso numero, si riaccende da solo; quelli che hai messo in pausa tu o che abbiamo spento per errori, no.

# 1) one link per end-customer: your id + the webhook its number will have
curl -X POST https://api.waiaconnect.com/v1/onboarding-links \
  -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"externalId": "pharmacy-42", "label": "Pharmacy 42", "mode": "coexistence",
       "webhook": {"url": "https://api.yourcompany.com/hooks/connect"}}'
# → 201 { "publicId": "onb_…", "url": "https://…/c#<token>", "expiresAt": "…",
#         "webhook": { "secret": "whsec_…", "createdOnCompletion": true, … } }   ← store the secret NOW

# 2) send "url" to your customer. Then, on https://api.yourcompany.com/hooks/connect:
#    { "type": "onboarding.completed", "connection": { "id": "conn_…", "externalId": "pharmacy-42", … },
#      "data": { "onboardingLinkId": "onb_…", "reconnected": false, "webhookId": "wh_…", … } }
#    { "type": "onboarding.failed", "connection": { "id": null, … },
#      "data": { "externalId": "pharmacy-42", "reason": "meta_error", "metaErrorCode": 2655093,
#                "metaMessage": "The business is already sharing…", "linkUsable": true, … } }

# 3) or ask (polling) by your id
curl "https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "links": [ { "id": "onb_…", "status": "used", "connectionId": "conn_…",
#       "outcome": { "state": "completed", "connectionId": "conn_…", "webhookId": "wh_…", … } } ] }
curl https://api.waiaconnect.com/v1/onboarding-links/onb_… -H "Authorization: Bearer wc_live_YOUR_API_KEY"

# 4) the number's webhook, by your id (PATCH to change url/events, rotate-secret, test)
curl "https://api.waiaconnect.com/v1/webhooks?externalId=pharmacy-42" -H "Authorization: Bearer wc_live_YOUR_API_KEY"

# 5) offboarding: disconnecting the number switches its webhook off
#    (active: false, disabledReason: "connection_disconnected"); reconnecting it switches it back on

const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json" };

// 1) one link per end-customer: your id + the webhook its number will have
const link = await (await fetch("https://api.waiaconnect.com/v1/onboarding-links", {
  method: "POST", headers: H,
  body: JSON.stringify({ externalId: "pharmacy-42", label: "Pharmacy 42", mode: "coexistence",
    webhook: { url: "https://api.yourcompany.com/hooks/connect" } })
})).json();
await saveSecret("pharmacy-42", link.webhook.secret); // shown ONCE — it signs this customer's events
await sendToCustomer(link.url);

// 2) your webhook handler (verify the signature first — see «Verify the signature»)
app.post("/hooks/connect", express.raw({ type: "application/json" }), async (req, res) => {
  const evt = JSON.parse(req.body);
  if (evt.type === "onboarding.completed") await markConnected(evt.data.externalId, evt.connection.id);
  if (evt.type === "onboarding.failed") await tellCustomer(evt.data.externalId, evt.data.reason, evt.data.metaErrorCode, evt.data.linkUsable);
  res.sendStatus(200);
});

// 3) or poll by your id
const { links } = await (await fetch("https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42", { headers: H })).json();
console.log(links[0]?.outcome); // { state: "pending" | "completed" | "failed", reason, metaErrorCode, … }

<?php
function connect($method, $url, $body = null) {
  $ch = curl_init($url);
  curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer wc_live_YOUR_API_KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
  ]);
  return json_decode(curl_exec($ch), true);
}
// 1) one link per end-customer: your id + the webhook its number will have
$link = connect("POST", "https://api.waiaconnect.com/v1/onboarding-links", [
  "externalId" => "pharmacy-42", "label" => "Pharmacy 42", "mode" => "coexistence",
  "webhook" => ["url" => "https://api.yourcompany.com/hooks/connect"],
]);
save_secret("pharmacy-42", $link["webhook"]["secret"]); // shown ONCE

// 2) in your webhook handler: onboarding.completed / onboarding.failed (data.reason, data.metaErrorCode)
// 3) or poll by your id
$links = connect("GET", "https://api.waiaconnect.com/v1/onboarding-links?externalId=pharmacy-42")["links"];
$outcome = $links[0]["outcome"] ?? null; // state: pending | completed | failed

import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}

# 1) one link per end-customer: your id + the webhook its number will have
link = requests.post("https://api.waiaconnect.com/v1/onboarding-links", headers=H, json={
    "externalId": "pharmacy-42", "label": "Pharmacy 42", "mode": "coexistence",
    "webhook": {"url": "https://api.yourcompany.com/hooks/connect"},
}).json()
save_secret("pharmacy-42", link["webhook"]["secret"])  # shown ONCE

# 2) in your webhook handler: onboarding.completed / onboarding.failed (data.reason, data.metaErrorCode)
# 3) or poll by your id
links = requests.get("https://api.waiaconnect.com/v1/onboarding-links", headers=H, params={"externalId": "pharmacy-42"}).json()["links"]
outcome = links[0]["outcome"] if links else None  # state: pending | completed | failed

Senza webhook nel link, onboarding.completed e onboarding.failed vanno ai webhook dell'account (in onboarding.failed, connection.id è null: il tuo externalId è in data).

Un webhook con events esplicito che non include questi tipi non li riceve; uno con tutti gli eventi inizia a riceverli.

Nei link di attivazione, connectionId ora esce come conn_…; l'id interno resta in legacyConnectionId, che verrà ritirato.

outcome.state = failed anche quando il link è scaduto (link_expired) o l'hai annullato (link_revoked) prima che il cliente finisse.