Il tuo primo messaggio

Invia un testo WhatsApp, rileggi la conversazione e mostra al cliente la doppia spunta blu.

Inviare un testo

POST /messages

curl -X POST https://developers.wasync.app/api/v1/messages \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectionId":"conn_8f3a21","to":"40700000000","text":"Hi from my app 👋"}'

200 response

{
  "messageId": "cmqj3k2ab0001xyz",
  "waMessageId": "[email protected]_3EB0A1B2C3",
  "status": "sent"
}

to contiene solo cifre in formato internazionale, senza +, ad esempio 40700000000. text può contenere al massimo 4096 caratteri. Per i contenuti multimediali, indichi media al posto di text: { filename, mimetype, data (base64, ≤ 16 MB), caption? }. Deve essere presente esattamente uno dei due campi. Le note vocali usano mimetype: audio/ogg e un nome file voice-*.ogg. Usa whatsapp.send.

Imposti il timeout HTTP ad almeno 180 secondi

Un invio qr richiede normalmente 1–7 s, fino a circa 20 s per i testi lunghi, e il percorso di auto-ripristino può richiedere circa 2,5 minuti. Un invio cloud_api richiede circa 1 s. Un invio lento non è un errore: un client che rinuncia dopo 30 s e riprova invia il messaggio due volte al cliente. Passi sempre un idempotencyKey (un UUID per ogni invio logico) e riprovi con lo stesso valore.

Due id: usi quello giusto per i collegamenti

La risposta contiene due identificatori, che non sono intercambiabili.

Id	Dove compare	A cosa serve
`messageId` (un cuid)	`messageId` nella POST, `id` nella GET, `message.id` in entrambi i webhook	L'unico id utilizzabile per i collegamenti. Lo salvi all'invio, lo usi per la deduplicazione e per associare gli eventi `message.status`.
`waMessageId`	`waMessageId` (REST), `wa_id` (webhook), `wa_message_id` (invio di contenuti multimediali)	Ticket di supporto e debug. Può essere `null`: non lo usi mai per collegamenti o deduplicazione.

Vale la pena gestire un caso degradato: { "messageId": null, "waMessageId": "…", "status": …, "persisted": false } con HTTP 200 significa che il messaggio è stato consegnato ma non è stato salvato. Non lo riprovi.

Rileggere la conversazione

GET /messages

curl "https://developers.wasync.app/api/v1/messages?connectionId=conn_8f3a21&limit=20" \
  -H "Authorization: Bearer $WASYNC_API_KEY"

200 response

{
  "messages": [
    {
      "id": "cmqj3k2ab0001xyz",
      "waMessageId": "[email protected]_3EB0A1B2C3",
      "connectionId": "conn_8f3a21",
      "direction": "outgoing",
      "text": "Hi from my app 👋",
      "mediaUrl": null,
      "mediaType": null,
      "status": "delivered",
      "errorMessage": null,
      "createdAt": "2026-07-22T10:00:00.000Z"
    }
  ],
  "nextCursor": "cmqj3k2ab0001xyz",
  "hasMore": true
}

I messaggi sono ordinati dal più recente, con paginazione a cursore: limit va da 1 a 100 (predefinito 20), e cursor accetta il nextCursor della risposta precedente. Usa whatsapp.read.

Mostrare al cliente la doppia spunta blu

POST /messages/read

curl -X POST https://developers.wasync.app/api/v1/messages/read \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectionId":"conn_8f3a21","phone":"40700000000"}'

Chiami questo endpoint quando un operatore apre la conversazione nella sua interfaccia. Altrimenti nessuno apre mai la chat in WhatsApp, i messaggi del cliente restano con la doppia spunta grigia e la conversazione sembra ignorata. Il corpo della richiesta è { connectionId, phone?, messageId? }, con almeno uno tra phone e messageId (il cuid di un messaggio in arrivo; se sono presenti entrambi, prevale messageId). Usa whatsapp.send, non whatsapp.read, perché trasmette una conferma di lettura al cliente. È idempotente, senza chiave e senza limite di frequenza. Restituisce { "ok": true, "marked": 3 }.

Passi successivi

Per ricevere una notifica dei messaggi in arrivo invece di fare polling: Webhooks.
Per costruire il tutto senza codice: n8n o MCP.
Per generare un client dal contratto: npx @openapitools/openapi-generator-cli generate -i https://developers.wasync.app/openapi.json -g typescript-fetch -o ./wasync-client

Questa pagina è stata utile?