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.

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:

Segmenti

A questo nodo sono collegati i segmenti di seguito:

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

Formati dei numeri di telefono

I numeri di telefono nella richiesta contacts possono essere in qualsiasi formato componibile.

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

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.

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:

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:

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:

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: