/v1/contacts
Utilizza il nodo contacts
per gestire gli utenti WhatsApp nel tuo database convalidandoli prima di inviare messaggi e verifica l'identità di un utente con gli hash di identità.
Con il nodo contacts
puoi:
status
sia valid
prima di inviare un messaggio a un utente. A partire dalla versione 2.39.1, il nodo messages
può essere utilizzato direttamente con un numero di telefono, senza doverlo prima tradurre in un ID WhatsApp mediante il nodo contacts
.
Stiamo riadattando il nodo contacts
in modo tale che a partire dalla versione 2.43 non fornisca più informazioni sullo stato di un numero di telefono. A prescindere che l'utente disponga o meno di WhatsApp, restituirà lo status
valid
nella risposta e un wa_id.
Devi includere un'opzione che consenta ai tuoi clienti di fornire un consenso esplicito per le comunicazioni WhatsApp con la tua azienda. Il flusso di ottenimento del consenso esplicito è gestito dalla tua azienda. Una volta che il cliente ha fornito un consenso esplicito, utilizza il nodo contacts
per convalidare il numero registrato. Per ulteriori informazioni, consulta Informazioni su come ottenere un consenso esplicito per WhatsApp.
Se un'azienda usa in modo improprio l'endpoint, verranno intraprese le seguenti azioni:
Ti consigliamo di verificare i contatti prima di inviare messaggi. Tuttavia, non è necessario eseguire questa verifica quando rispondi ai messaggi in arrivo da un cliente: puoi rispondere immediatamente utilizzando il wa_id
fornito. Non sono previsti costi aggiuntivi in quanto i risultati vengono memorizzati nella cache.
Prima di inviare messaggi agli utenti che hanno fornito la loro approvazione, invia una richiesta POST
all'endpoint /v1/contacts
per creare una richiesta di convalida utente dell'account WhatsApp. Nella chiamata, includi una lista di numeri di telefono che desideri convalidare.
POST /v1/contacts { "blocking": "wait" | "no_wait", "contacts": [ "16315551000", "+1 631 555 1001", "6315551002", "+1 (631) 555-1004", "1-631-555-1005" ], "force_check": false | true }
Riceverai una risposta con lo status
attuale dei numeri richiesti e i relativi ID WhatsApp (wa_id
):
{ "contacts": [ { "wa_id": "16315551000", "input": "16315551000", "status": "valid" }, { "wa_id": "16315551001", "input": "+1 631 555 1001", "status": "processing" # Only applicable when request is non-blocking }, { "input": "6315551002", "status": "invalid" }, { "input": "+163155588", "status": "failed" } }
Salva gli ID WhatsApp per quei numeri per i quali lo status
restituito è valid
. Gli utenti validi sono quelli con un account WhatsApp. Usa gli ID WhatsApp per inviare messaggi e notifiche.
Ripeti questi passaggi regolarmente per gestire la tua lista di utenti validi. I risultati vengono memorizzati nella cache del database del client API On-Premises di WhatsApp Business per 7 giorni.
I parametri seguenti sono supportati per chiamate POST
a /v1/contacts
:
Nome | Descrizione |
---|---|
| Facoltativo. Se la richiesta deve attendere o meno il completamento dell'elaborazione prima di restituire una risposta. Per maggiori informazioni, leggi la sezione Blocco di seguito. Valori possibili: |
| Obbligatorio. Array di numeri di telefono che stai convalidando. I numeri di telefono possono essere in qualsiasi formato standard. Il formato consigliato per i numeri di telefono dei contatti è un segno più ( |
| Facoltativo. Se controllare o meno la cache dei contatti. Le informazioni di contatto normalmente vengono memorizzate nella cache per 7 giorni. Impostando il parametro Valori possibili: |
A questo nodo sono collegati i segmenti di seguito:
Segmento | Descrizione |
---|---|
Usa questo segmento per gestire le identità degli utenti. Per ulteriori informazioni, consulta Comprensione del cambio di identità per WhatsApp Business. |
Esistono due opzioni per il parametro blocking
: no_wait
e wait
. Se il parametro blocking
non è specificato in una chiamata, è no_wait
per impostazione predefinita.
Il parametro blocking
determina se la richiesta deve attendere il completamento dell'elaborazione (sincrona) o meno (asincrona).
Impostazione | Descrizione |
---|---|
| L'elaborazione dei numeri di telefono è asincrona. La risposta può includere alcuni numeri con
|
| L'elaborazione dei numeri di telefono è sincrona. Vedi lo stato finale di tutti i contatti dopo la sincronizzazione con il server. Questa impostazione fa in modo che il blocco delle query attenda fino a quando non viene eseguita la verifica di tutti i numeri, restituendo i risultati. Questa operazione potrebbe richiedere del tempo. |
I numeri di telefono nella richiesta contacts
possono essere in qualsiasi formato componibile.
Quando non è presente il segno più (+
) all'inizio del numero di telefono, il prefisso internazionale viene determinato utilizzando il numero di telefono sotto cui è registrato il tuo client dell'API On-Premises di WhatsApp Business; di conseguenza, i numeri di telefono associati a un prefisso internazionale diverso genereranno errore.
La best practice consigliata è quella di specificare sempre il prefisso internazionale con il numero di telefono preceduto dal segno più (+
).
Il prefisso internazionale può essere comunque usato se il numero dopo +
non è valido. Si consiglia di convalidare i numeri di telefono prima di usare l'API On-Prem per ottenere comportamenti prevedibili.
Di seguito sono riportati alcuni esempi a dimostrazione di questo comportamento, supponendo che il client dell'API On-Premises di WhatsApp Business sia registrato con un numero di telefono indiano (il cui prefisso internazionale è +91
):
Numero di telefono | Numero di telefono tradotto |
---|---|
|
|
|
|
|
|
|
|
|
|
Il payload della risposta contacts
contiene lo stesso array di numeri di telefono inviato nella richiesta con le proprietà input
, status
e wa_id
.
Nome | Descrizione |
---|---|
| Il valore inviato nel campo |
v2.41 e precedenti | Lo stato dell'utente. Valori possibili:
|
v2.43 e successive | Lo stato dell'utente. Valori possibili:
|
v2.41 e precedenti | ID utente di WhatsApp che può essere utilizzato in altre chiamate. Restituito solo se |
v2.43 e successive | ID utente di WhatsApp restituito, che può essere o meno valido. Poiché non ci sono garanzie che il valore sia valido, non utilizzarlo in chiamate successive. |
Oltre allo stato processing
, dovresti vedere uno stato HTTP di 200 OK
.
Se invii un modello di messaggio a un numero di telefono non associato a un account WhatsApp, riceverai il messaggio di errore "Utente non valido" con il codice di errore 1013
.
Nel caso in cui sia presente un qualsiasi altro errore nella risposta, fai riferimento a Messaggi di errore e di stato.
Il blocco può essere considerato una funzione difensiva per impedire ad autori di atti illeciti di continuare a commettere azioni dannose. Per bloccare un contatto, questo deve averti inviato un messaggio nelle 24 ore precedenti.
Invia una chiamata API a /v1/contacts/{phone_number}/block
indicando una motivazione per bloccare un altro account WhatsApp.
POST /v1/contacts/+16315551000/block { "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked" }
Una risposta corretta ha lo stato HTTP 200
e nessun oggetto "errors".
Una risposta di errore è simile a questa:
{ "errors": [ { "code": 2048, "title": "Not engaged contact", "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs." } ] }
I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/block
:
Impostazione | Descrizione |
---|---|
| Facoltativo. Campo libero per la motivazione del blocco. Viene utilizzato in caso di blocco di un altro account WhatsApp. Deve contenere meno di 60 caratteri. |
| Obbligatorio. I numeri di telefono possono essere in qualsiasi formato standard. Il formato consigliato per i numeri di telefono dei contatti è un segno più (+) seguito dal prefisso internazionale. Per ulteriori informazioni, consulta Formati dei numeri di telefono. |
Effettua questa chiamata per sbloccare un contatto.
Invia una chiamata API a /v1/contacts/{phone_number}/unblock
.
POST /v1/contacts/+16315551000/unblock
Una risposta corretta ha lo stato HTTP 200
e nessun oggetto "errors".
Una risposta di errore è simile a questa:
{ "errors": [ { "code": 1009, "title": "Parameter value is not valid", "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code" } ] }
I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/unblock
:
Impostazione | Descrizione |
---|---|
| Obbligatorio. I numeri di telefono possono essere in qualsiasi formato standard. Il formato consigliato per i numeri di telefono dei contatti è un segno più (+) seguito dal prefisso internazionale. Per ulteriori informazioni, consulta Formati dei numeri di telefono. |
Ecco come puoi ottenere una lista dei tuoi contatti bloccati.
Invia una chiamata API a /v1/contacts/blocklist
per ricevere una lista dei contatti bloccati sottoposta a paginazione.
GET /v1/contacts/blocklist?limit=10&offset=0
Riceverai una risposta contenente una pagina con la lista dei tuoi contatti bloccati insieme alle relative informazioni di paginazione.
{ "contacts": [ { "wa_id": "16315551000@s.whatsapp.net" } ], "pagination": { "limit": 10, "offset": 0, "total": 1 } }
I parametri seguenti sono supportati per chiamate GET a /v1/contacts/blocklist
:
Impostazione | Descrizione |
---|---|
| Facoltativo. L'intervallo accettato è [0; 200]. Valore predefinito: 100. |
| Facoltativo. Valore predefinito: 0. |
La segnalazione fornisce segnali cruciali per creare una soluzione preventiva contro gli autori di atti illeciti. Per segnalare un contatto, questo deve averti inviato un messaggio nelle 24 ore precedenti.
Invia una chiamata API a /v1/contacts/{phone_number}/report
indicando una motivazione per il blocco di un altro account WhatsApp.
POST /v1/contacts/+16315551000/block { "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked", "block": "true | false optional boolean with default of false", "message_id": "message-id. Optional reported message id" }
Una risposta corretta ha lo stato HTTP 200
e nessun oggetto "errors".
Una risposta di errore è simile a questa:
{ "errors": [ { "code": 2048, "title": "Not engaged contact", "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs." } ] }
I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/block
:
Impostazione | Descrizione |
---|---|
| Facoltativo. Campo libero per la motivazione del blocco. Viene utilizzato in caso di blocco di un altro account WhatsApp. Deve contenere meno di 60 caratteri. |
| Facoltativo. L'impostazione predefinita è Se segnalare il contatto o segnalarlo e bloccarlo. |
| Facoltativo. L'ID del messaggio da segnalare. Se non specificato, saranno inviati a WhatsApp gli ultimi 5 messaggi. |
| Obbligatorio. I numeri di telefono possono essere in qualsiasi formato standard. Il formato consigliato per i numeri di telefono dei contatti è un segno più (+) seguito dal prefisso internazionale. Per ulteriori informazioni, consulta Formati dei numeri di telefono. |