API On-Premises della piattaforma WhatsApp Business

Piattaforma WhatsApp Business > API On-Premises > Riferimento

Stiamo disattivando l'API On-Premises. Consulta il nostro documento Disattivazione API On-Premises per i dettagli e per scoprire come eseguire la migrazione alla nostra API Cloud di nuova generazione.

Impostazioni dell'app

Le impostazioni dell'app per il tuo client On-Premises di WhatsApp Business.

Requisiti

  • Le richieste devono essere effettuando usando il tuo account admin
  • Tutte le risposte devono includere 200 OK HTTPS

Lettura

Ottieni le attuali impostazioni dell'app per il tuo client On-Premises di WhatsApp Business.

Esempio

Invia una richiesta GET all'endpoint /v1/settings/application per ottenere le attuali impostazioni dell'app.

GET /v1/settings/application

In caso di successo, la risposta contiene 200 OK e un payload JSON contenente un oggetto application che elenca tutte le attuali impostazioni dell'applicazione e i rispettivi valori.

Esempio di risposta

{
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "garbagecollector_enable": {
                "media": false,
                "messages": true
            },
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio",
                    "document"
                ]
            },
            "notify_user_change_number": true,
            "show_security_notifications": true,
            "unhealthy_interval": 30,
            "wa_id": "16315551019",
            "webhooks": {
               	"url": "<Webhook URL, https>",
               	"max_concurrent_requests": max-concurrent-requests,
               	"message": { // Available for v2.41.2 and above
                  	"sent": true,
                  	"delivered": true,
                  	"read": false
                 },
             },
             "verbose_logging": false,
             "log_level" : "info"
         },
    },
    "meta": {
        "api_status": "stable",
        "version": "3.0.1"
    }
}

Segmenti

SegmentoDescrizione

/media/providers

Utilizzato per gestire una lista di provider di contenuti multimediali per l'invio di link a contenuti multimediali.

Aggiornamento

Per configurare le impostazioni dell'app, invia una richiesta PATCH all'endpoint /v1/settings/application con un oggetto JSON contenente i nomi e i valori dei campi da impostare.

Per le campagne di messaggistica che coinvolgono un gran volume di messaggi, si raccomanda di disabilitare la garbage collection automatica impostando garbagecollector_enable.messages su false e di riabilitarla una volta terminata la campagna impostandola di nuovo su true.

Puoi verificare se la garbage collection automatica è disabilitata inviando una richiesta GET all'endpoint /v1/settings/application e leggendo la proprietà garbagecollector_enable.

Esempio di richiesta

PATCH /v1/settings/application
{
    "callback_persist": true | false,
    "max_callback_backoff_delay_ms": max-delay-in-ms,
    "media": {
        "auto_download": ["audio", "document", "voice", "video", "image", "sticker"]
    }
    "callback_backoff_delay_ms": "delay-in-ms",
    "heartbeat_interval": heartbeat-interval-in-secs,
    "unhealthy_interval": unhealthy-interval-in-secs,
    "webhooks": { 
        # See the Webhooks Parameters table below for more information
        "max_concurrent_requests": max-concurrent-requests,
        "url": "<Webhook URL, https>",
        "message": {              // Available on v2.41.2 and above
                "sent": false,
                "delivered": true,
                "read": false
           },
    },
    "axolotl_context_striping_disabled": false | true,
    "notify_user_change_number": false | true,
    "show_security_notifications": false | true,
    # Available on v2.49.1 and above
    "garbagecollector_enable": {
        "messages": true | false,
        "media": true | false
    }
    "skip_referral_media_download": true | false,
    "webhook_payload_conversation_pricingmodel_disabled": false | true
    # Available on v2.51.1 and above
    "verbose_logging": false | true,
    "log_level" : log-level-str,
}

In caso di azione eseguita correttamente, la risposta conterrà 200 OK con un oggetto null o JSON.

Se si verificano errori, consulta Messaggi di errore e di stato.

Parametri

Alcune impostazioni richiedono il riavvio di Coreapp per rendere effettive le modifiche. Tali impostazioni sono callback_persist, garbagecollector_enable, verbose_logging, log_level e webhooks: max_concurrent_requests.

`log_level`
NomeDescrizione

axolotl_context_striping_disabled

tipo: booleano

Influisce sui limiti di connessione del database.


v2.25 migliora le prestazioni in uscita e in entrata rispetto alle versioni precedenti. Questa ottimizzazione si basa sulla creazione di ulteriori connessioni al database. Per alcune distribuzioni, ciò può causare il raggiungimento dei limiti di connessione al database. In tal caso, imposta la configurazione axolotl_context_striping_disabled su true per disabilitare questa funzione di miglioramento delle prestazioni. Non vi sono altri effetti sulle funzionalità di Coreapp.


Valori:true, false (predefinito)

Richiesto riavvio di Coreapp.

callback_backoff_delay_ms

tipo: stringa

Ritardo di backoff per una callback non riuscita in millisecondi.


Questa impostazione viene utilizzata per configurare la quantità di tempo di ritardo del backoff prima di ritentare una callback non riuscita. Il ritardo di backoff aumenta linearmente di questo valore ogni volta che una callback non ottiene una risposta HTTPS 200 OK. Il ritardo di backoff è limitato dall'impostazione max_callback_backoff_delay_ms. Ad esempio, se una callback fallisce la prima volta, effettuerà un nuovo tentativo dopo 3000 ms (3 s). Un secondo tentativo non andato a buon fine comporterà un ritardo di 6000 ms (6 s) prima di un nuovo tentativo. Il processo continua fino a quando la callback non ha esito positivo o il ritardo non raggiunge 900 000 ms (15 minuti), dopodiché saranno eseguiti nuovi tentativi di callback, ma il ritardo non aumenterà.


Impostazione predefinita: 3000

callback_persist

tipo: booleano

Memorizza le callback su disco finché non vengono riconosciute correttamente o meno dal webhook. Messaggi e callback sono archiviati in un database locale per garantire che vengano consegnati correttamente prima di essere rimossi dal database. Questo protegge le callback nel caso in cui il client o il server dell'API di WhatsApp Business si blocchi.
Le notifiche che non vengono eseguite correttamente (nessuna risposta HTTPS 200) vengono ritentate a tempo indefinito. Utilizza questa impostazione per configurare i tentativi di reinvio.


Valori:true (predefinito), false
Necessario riavvio di Coreapp.

db_garbagecollector_enable

tipo: booleano

Questo campo è stato dichiarato obsoleto a partire dalla v2.39.


Abilita la garbage collection automatica dei dati obsoleti del database dei messaggi per assistere nella gestione del database.


Questo parametro è false per gli utenti che avevano pass_through impostato su false prima della v2.29. Ti consigliamo di abilitare questa impostazione per assicurarti che il tuo database funzioni con stabilità. Se desideri disabilitare questa impostazione, ti consigliamo di considerare l'utilizzo dell'endpoint /services/message/gc per gestire il database.


Valori:true (predefinito), false

Richiesto riavvio di Coreapp.

garbagecollector_enable

tipo: oggetto Garbage collector

Abilita la garbage collection automatica di messaggi e contenuti multimediali.


Ti consigliamo di abilitare l'impostazione di garbage collection di messaggi e contenuti multimediali per garantire la rimozione di righe e file vecchi/inutilizzati. Se disabilitato, il garbage collector può essere avviato usando gli endpoint /services/message/gc e /services/media/gc. Consulta la tabella sui parametri del garbage collector per i valori.


Richiesto riavvio di Coreapp.

heartbeat_interval

tipo: intero

Intervallo del monitoraggio del nodo Master dei nodi Coreapp in secondi.


Impostazione predefinita: 5
Si applica alle configurazioni di Multiconnect.

max_callback_backoff_delay_ms

tipo: stringa

Ritardo massimo per una callback non riuscita in millisecondi. Per maggiori informazioni, leggi la descrizione per callback_backoff_delay_ms di seguito.


Impostazione predefinita: 900000

media

tipo: array

Elenco di contenuti multimediali per il download automatico. Consulta Impostazioni di download automatico dei contenuti multimediali per maggiori informazioni.

notify_user_change_number

tipo: booleano

Influisce sulla notifica di sistema user_changed_number.


Valori:true, false (predefinito)

pass_through

tipo: booleano

A partire dalla versione v2.35, non puoi più riabilitare l'impostazione pass_through per i client dell'API di WhatsApp Business.


Consente di eliminare i singoli messaggi o di archiviarli in un database locale dopo che sono stati consegnati o letti.


Quando i messaggi vengono inviati, vengono archiviati in un database locale, utilizzato come cronologia dell'app. Poiché l'azienda mantiene la propria cronologia, puoi specificare se desideri o meno il pass_through del messaggio.

  • Quando true, rimuove i messaggi dal database locale dopo essere stati consegnati o letti dal destinatario.
  • Quando false, salva tutti i messaggi nella memoria locale fino a quando non vengono eliminati automaticamente (ovvero db_garbagecollector_enable è true) o in modo esplicito (ovvero db_garbagecollector_enable è false). Consulta la documentazione sui Servizi per maggiori informazioni.

Ti consigliamo di disabilitare pass_through in modo che la callback status possa funzionare come previsto.


Valori:true, false (predefinito)

Richiesto riavvio di Coreapp.

show_security_notifications

tipo: booleano

Se abilitato, riceverai una notifica webhook user_identity_changed quando il client API di WhatsApp Business rileva che un utente con cui stai conversando è potenzialmente cambiato. Quando ciò accade, tutti i messaggi in uscita per l'utente vengono bloccati fino ad avvenuta conferma del cambio di identità mediante l'endpoint identity.


Valori:true, false (predefinito)

skip_referral_media_download

tipo: booleano

Se impostato su true, l'immagine o il video su cui l'utente ha cliccato in un'inserzione che rimanda a WhatsApp non viene scaricato.


Impostazione predefinita:false

unhealthy_interval

tipo: intero

Numero massimo di secondi in cui un nodo Master attende che un nodo Coreapp risponda a un heartbeat prima di considerarlo non correttamente funzionante e avviare il processo di failover.


Impostazione predefinita: 30
Si applica alle configurazioni di Multiconnect.

webhook_payload_conversation_pricingmodel_disabled

tipo: booleano

Questo campo è stato dichiarato obsoleto a partire dalla v2.39.

Controlla l'inclusione di payload di informazioni su conversazione e prezzi nelle notifiche di stato dei messaggi.


Valori:true, false (predefinito)

Non è richiesto il riavvio di Coreapp.

webhooks

tipo: oggetto Webhooks

Obbligatorio quando si utilizzano i webhook.

Fornisci l'URL del tuo webhook. Se l'URL del webhook non è impostato, le callback vengono ignorate. Guarda l'App test di esempio per scoprire come vedere e testare con facilità i tuoi webhook.


Puoi convalidare gli eventi del webhook specificando una chiave segreta condivisa come parametro di query quando imposti l'URL del webhook. Esempio: https://url?auth='[shared_secret]'.

L'URL del webhook. Ad esempio: https://spotless-process.glitch.me/webhook.


Se l'URL del webhook non è impostato, le callback vengono ignorate. Le callback costituiscono un canale importante per consegnare notifiche tempestive ed errori fuori banda; pertanto, è altamente consigliato configurare l'endpoint dell'URL del webhook. Per dettagli sui campi del webhook, consulta la tabella Parametri webhook di seguito.

verbose_logging

tipo: booleano

Abilita la registrazione dettagliata nei Coreapp. Questo livello di registrazione deve essere utilizzato solo per scopi di test a causa dell'elevato volume di output. Se impostato su true, l'attributo log_level viene ignorato.


Valori:true, false (predefinito)

log_level

tipo: oggetto Webhooks

Configura il livello di registrazione nei Coreapp. Ogni livello riduce gradualmente la quantità di output di registro: info ha il maggior numero di informazioni, mentre fatal contiene solo errori critici.


Valori:info (predefinito), warning, error, fatal

Parametri webhook

NomeDescrizione

max_concurrent_requests

tipo: intero

Configura il numero massimo di richieste di callback attive inviate.


Valori:6 (predefinito), 12, 18 o 24
Necessario riavvio di Coreapp.

url

tipo: stringa

Le notifiche in entrata e in uscita sono indirizzate a questo URL. Per ulteriori informazioni, consulta la Documentazione sui webhook.


È richiesto un endpoint basato su HTTPS; HTTP non funzionerà.
Esempio:https://spotless-process.glitch.me/webhook

message

tipo: oggetto Messages

Disponibile a partire dalla v2.41.2

Nidificato nell'oggetto webhooks, abilita i client a impostare il messaggio correlato alle notifiche webhook che si desidera ricevere da questa lista: sent, delivered, read. Maggiori informazioni su questi stati sono disponibili qui.


L'azienda può decidere di ricevere o meno queste notifiche webhook impostando i valori su true (predefinito) o su false.

Parametri dei contenuti multimediali

NomeDescrizione

auto_download

tipo: array

Specifica quali tipi di contenuti multimediali scaricare automaticamente.


Valori:audio, document, voice, video, image, sticker

Parametri del garbage collector

NomeDescrizione

messages

tipo: booleano

Configura la garbage collection dei messaggi.


Valori:true (predefinito), false
Necessario riavvio di Coreapp.

media

tipo: booleano

Configura la garbage collection dei contenuti multimediali.


Valori:true, false (predefinito)
Necessario riavvio di Coreapp.

Ripristino alle impostazioni predefinite

Per ripristinare tutte le impostazioni dell'app ai rispettivi valori predefiniti, invia una richiesta DELETE all'endpoint /v1/settings/application.

Esempio di richiesta

DELETE /v1/settings/application

In caso di azione eseguita correttamente, la risposta conterrà 200 OK con null o {}.

Se si verificano errori, consulta Messaggi di errore e di stato.