Contatti

/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:

  • Verificare che un numero di telefono nel database appartenga a un account WhatsApp valido. Assicurati che status sia valid prima di inviare un messaggio a un utente.
  • Ottenere l'ID WhatsApp di un numero di telefono. Gli ID WhatsApp sono necessari per inviare messaggi e notifiche agli utenti.

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 statusvalid nella risposta e un wa_id.

Prima di iniziare

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.

Limitazioni

  • Usa questo endpoint per verificare che un numero di telefono nel database di un'azienda appartenga a un account WhatsApp valido.
  • Il numero di chiamate non deve superare il numero di messaggi inviati dal numero di telefono.

Applicazione delle normative

Se un'azienda usa in modo improprio l'endpoint, verranno intraprese le seguenti azioni:

  • Se si sospetta un uso improprio, tutti gli amministratori elencati in Business Manager riceveranno un avviso iniziale tramite e-mail.
  • L'azienda avrà sette giorni dalla ricezione dell'avviso per modificare il proprio comportamento.
  • Se dopo sette giorni le chiamate non sono state adeguate, il numero di telefono verrà disabilitato in modo permanente.

Consigli

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.

Creazione

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.

Esempio

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.

Parametri

I parametri seguenti sono supportati per chiamate POST a /v1/contacts:

Nome Descrizione

blocking

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:no_wait (predefinito), wait

contacts

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ù (+) seguito dal prefisso internazionale. Per ulteriori informazioni, consulta la sezione Formati dei numeri di telefono di seguito.

force_check

Facoltativo.

Se controllare o meno la cache dei contatti. Le informazioni di contatto normalmente vengono memorizzate nella cache per 7 giorni. Impostando il parametro force_check su true, la cache verrà bypassata assicurando che venga eseguita una verifica.


Valori possibili:false (predefinito), true

Segmenti

A questo nodo sono collegati i segmenti di seguito:

SegmentoDescrizione

/{user-whatsapp-id}/identity

Usa questo segmento per gestire le identità degli utenti. Per ulteriori informazioni, consulta Comprensione del cambio di identità per WhatsApp Business.

Blocco

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).

ImpostazioneDescrizione

no_wait

L'elaborazione dei numeri di telefono è asincrona.


La risposta può includere alcuni numeri con status impostato su processing. Se si verifica questa situazione, ti consigliamo di seguire questi passaggi:

  1. Riceverai una risposta con alcuni numeri contrassegnati come processing.
  2. Invia un'altra richiesta per la verifica dei contatti che includa i numeri con lo stato processing.
  3. Se l'elaborazione viene eseguita nella tua nuova richiesta, ricevi uno stato corretto per quel determinato numero (valido o non valido).
  4. Se vedi ancora numeri contrassegnati come processing, ripeti il passaggio 2 fino a quando non ottieni una risposta per ogni numero.

wait

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.

Formati dei numeri di telefono

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 telefonoNumero di telefono tradotto

"+1-631-555-1002"

"+16315551002"

"6315551002"

"+916315551002"

"1-631-555-1002"

"+9116315551002"

"+1 (516) 283-7151"

"+15162837151"

"+54 9 11 5612-1008"

"+5491156121008"

Campi restituiti

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

input

Il valore inviato nel campo contacts della richiesta.

status

v2.41 e precedenti

Lo stato dell'utente.


Valori possibili:

  • processing: l'input è ancora in fase di elaborazione
  • valid: un utente WhatsApp valido
  • invalid: non è un utente WhatsApp valido
  • failed: si è verificato un errore durante l'elaborazione di questo controllo

status

v2.43 e successive

Lo stato dell'utente.


Valori possibili:

  • processing: l'input è ancora in fase di elaborazione
  • valid: il controllo dei contatti è completo e si può procedere all'invio del messaggio
  • failed: si è verificato un errore durante l'elaborazione di questo controllo

wa_id

v2.41 e precedenti

ID utente di WhatsApp che può essere utilizzato in altre chiamate. Restituito solo se status è valid.

wa_id

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.

Blocco dei contatti

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.

Esempio

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."
        }
    ]
}

Parametri

I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/block:

ImpostazioneDescrizione

reason

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.

phone_number

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.

Sblocco dei contatti

Effettua questa chiamata per sbloccare un contatto.

Esempio

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"
        }
    ]
}

Parametri

I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/unblock:

ImpostazioneDescrizione

phone_number

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.

Lista di elementi bloccati

Ecco come puoi ottenere una lista dei tuoi contatti bloccati.

Esempio

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
   }
}

Parametri

I parametri seguenti sono supportati per chiamate GET a /v1/contacts/blocklist:

ImpostazioneDescrizione

limit

Facoltativo.

L'intervallo accettato è [0; 200]. Valore predefinito: 100.

offset

Facoltativo.

Valore predefinito: 0.

Segnalazione

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.

Esempio

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."
        }
    ]
}

Parametri

I parametri seguenti sono supportati per chiamate POST a /v1/contacts/{phone_number}/block:

ImpostazioneDescrizione

reason

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.

block

Facoltativo.

L'impostazione predefinita è False.

Se segnalare il contatto o segnalarlo e bloccarlo.

message_id

Facoltativo.

L'ID del messaggio da segnalare. Se non specificato, saranno inviati a WhatsApp gli ultimi 5 messaggi.

phone_number

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.