API Local da Plataforma do WhatsApp Business

A API Local está sendo descontinuada. Consulte o documento Descontinuação da API Local para ver mais informações e saber como migrar para nossa API de Nuvem de última geração.

Configurações do app

As configurações do app para o cliente da API Local do WhatsApp Business.

Requisitos

  • As solicitações devem ser feitas por meio da sua conta admin.
  • Todas as respostas precisam incluir o código 200 OK HTTPS.

Ler

Receba as configurações atuais do app para o cliente da API Local do WhatsApp Business.

Exemplo

Envie uma solicitação GET ao ponto de extremidade /v1/settings/application para receber as configurações atuais do app.

GET /v1/settings/application

Se for bem-sucedida, a resposta retornará 200 OK e uma carga JSON contendo um objeto application que lista todas as configurações do app, bem como os valores correspondentes.

Exemplo de resposta

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

Bordas

BordaDescrição

/media/providers

Gerencie uma lista de fornecedores de mídia para enviar links de mídia.

Atualizar

Para atualizar as configurações do app, envie uma solicitação PATCH ao ponto de extremidade /v1/settings/application com um objeto JSON contendo os nomes e os valores de campo a serem definidos.

Nas campanhas de envio de mensagens que enviarão alto volume de mensagens, recomendamos desabilitar a coleta automática de lixo definindo garbagecollector_enable.messages como false; quando a campanha terminar, defina como true novamente.

É possível verificar se a coleta automática de lixo está desabilitada ao verificar a propriedade garbagecollector_enable em uma solicitação GET a /v1/settings/application.

Exemplo de solicitação

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

Se bem-sucedida, a resposta retornará 200 OK com null ou um objeto JSON.

Se houver algum erro, consulte Mensagens de erro e status.

Parâmetros

Algumas configurações exigem que o Coreapp seja reiniciado para que as alterações entrem em vigor. Essas configurações são callback_persist, garbagecollector_enable, verbose_logging, log_level e webhooks.max_concurrent_requests.

`log_level`
NomeDescrição

axolotl_context_striping_disabled

Tipo: booliano

Afeta os limites de conexão do banco de dados.


Melhor desempenho de saída e de entrada na v2.25. Essa otimização depende da criação de conexões adicionais do banco de dados. Para algumas implementações, isso pode fazer com que os limites de conexão do banco de dados sejam atingidos. Se for esse o caso, defina a configuração axolotl_context_striping_disabled como true para desabilitar esse recurso de melhoria de desempenho. Não há nenhum outro efeito nas outras funcionalidades do Coreapp.


Valores:true, false (padrão)

Reinicialização obrigatória do Coreapp.

callback_backoff_delay_ms

Tipo: string

Atraso de retirada para um retorno de chamada com falha em milissegundos.


Essa configuração é usada para definir o tempo dos atrasos de retirada antes de tentar fazer um novo retorno de chamada que falhou anteriormente. O atraso de retirada aumenta linearmente de acordo com esse valor cada vez que um retorno de chamada não obtém uma resposta HTTPS 200 OK. O atraso de retirada é limitado pela configuração max_callback_backoff_delay_ms. Por exemplo, se um retorno de chamada falhar da primeira vez, ele tentará novamente em 3.000ms (3 segundos). Uma segunda falha resultará em um atraso de 6.000ms (6 segundos) antes da nova tentativa. Isso continua até o retorno de chamada ser bem-sucedido ou o atraso alcançar 900.000ms (15 minutos). Depois disso, haverá nova tentativa de retorno de chamada, mas o atraso não aumentará.


Padrão: 3000.

callback_persist

Tipo: booliano

Armazena os retornos de chamada em disco até que eles sejam reconhecidos com sucesso ou não pelo Webhook. As mensagens e os retornos de chamada são armazenados em um banco de dados local para garantir que sejam entregues com sucesso antes de serem removidos do banco de dados local. Essa ação protege os retornos de chamada quando o cliente ou o servidor da WhatsApp Business API fica inoperante.
As notificações que não tiverem sucesso (sem resposta HTTPS 200) passarão por novas tentativas por tempo indefinido. Use essa configuração para definir a nova tentativa.


Valores:true (padrão), false.
Reinicialização obrigatória do Coreapp.

db_garbagecollector_enable

Tipo: booliano

Este campo ficou obsoleto na versão 2.49.


Habilita a coleta automática de lixo do banco de dados de mensagens para auxiliar no gerenciamento do banco.


Este parâmetro é false para usuários que tenham definido o pass_through como false antes da v2.29. Recomendamos que você habilite essa configuração para garantir que o banco de dados funcione de maneira estável. Se quiser desabilitá-la, considere usar o ponto de extremidade /services/message/gc para gerenciar o banco de dados.


Valores:true (padrão), false.

Reinicialização obrigatória do Coreapp.

garbagecollector_enable

Tipo: objeto do coletor de lixo

Habilita a coleta automática de lixo de mensagens e mídia.


Recomendados o uso da configuração de coleta de lixo de mensagens e mídia para garantir a remoção de linhas e arquivos antigos/não utilizados. Se estiver desabilitada, o coletor de lixo poderá ser iniciado usando os pontos de extremidade /services/message/gc e /services/media/gc. Confira os valores na tabela de parâmetros do coletor de lixo.


Reinicialização obrigatória do Coreapp.

heartbeat_interval

Tipo: número inteiro

O intervalo, em segundos, do monitoramento dos nós do Coreapp pelo nó mestre.


Padrão: 5.
Aplica-se a configurações de multiconexão.

max_callback_backoff_delay_ms

Tipo: string

Atraso máximo para um retorno de chamada com falha em milissegundos. Para mais informações, leia a descrição de callback_backoff_delay_ms abaixo.


Padrão: 900000.

media

Tipo: matriz

Lista de mídias para download automático. Consulte Parâmetros de mídia de download automático para saber mais.

notify_user_change_number

Tipo: booliano

Afeta a notificação de sistema user_changed_number.


Valores:true, false (padrão)

pass_through

Tipo: booliano

A partir da v2.35, não será mais possível reabilitar a configuração pass_through para clientes da WhatsApp Business API.


Permite que mensagens individuais sejam excluídas ou armazenadas em um banco de dados local após terem sido entregues ou lidas.


Quando enviadas, as mensagens são armazenadas em um banco de dados local. Esse banco de dados é usado como o histórico do app. Como as empresas mantêm o próprio histórico, você pode especificar se deseja pass_through de mensagens ou não.

  • Quando true, as mensagens são removidas do banco de dados local após serem entregues ou lidas pelo destinatário.
  • Quando false, todas as mensagens são salvas no armazenamento local até que sejam automaticamente excluídas (ou seja, db_garbagecollector_enable é true) ou excluídas de maneira explícita (ou seja, db_garbagecollector_enable é false). Consulte a documentação sobre serviços para saber mais.

Recomendamos que você desabilite o pass_through para que o retorno de chamada status funcione como esperado.


Valores:true, false (padrão)

Reinicialização obrigatória do Coreapp.

show_security_notifications

Tipo: booliano

Se habilitado, você receberá uma notificação user_identity_changed de Webhook quando o cliente da WhatsApp Business API detectar que um usuário com quem você está conversando tiver sido potencialmente alterado. Quando isso acontece, todas as mensagens de saída para esse usuário serão bloqueadas até que você reconheça a alteração de identidade dele usando o ponto de extremidade identity.


Valores:true, false (padrão)

skip_referral_media_download

Tipo: booliano

Se definido como true, não será possível baixar a imagem ou o vídeo em que o usuário clicou em um anúncio de clique para o WhatsApp.


Padrão:false.

unhealthy_interval

Tipo: número inteiro

Tempo máximo em segundos que um nó mestre aguarda a resposta do nó Coreapp para uma pulsação antes de o considerar não íntegro e começar o processo de failover.


Padrão: 30.
Aplica-se a configurações de multiconexão.

webhook_payload_conversation_pricingmodel_disabled

Tipo: booliano

Este campo foi descontinuado na versão 2.39.

Controla a inclusão de cargas de informações sobre conversa e preços nas notificações de status de mensagem.


Valores:true, false (padrão)

A reinicialização do Coreapp não é necessária.

webhooks

Tipo: objeto webhooks

Obrigatório ao usar Webhooks.

Forneça a URL do seu Webhook. Se a URL não for definida, os retornos de chamada serão perdidos. Consulte o exemplo de app de teste para obter uma forma simples de ver e testar seus Webhooks.


Você pode validar eventos de Webhook ao especificar uma chave secreta compartilhada como parâmetro de consulta durante a definição da URL do Webhook. Exemplo: https://url?auth='[shared_secret]'.

A URL do Webhook. Por exemplo: https://spotless-process.glitch.me/webhook.


Se a URL do Webhook não estiver definida, os retornos de chamada serão removidos. Os retornos de chamada são um canal importante para entregar notificações pontuais e erros fora da banda. Por isso, é altamente recomendado configurar o ponto de extremidade da URL do Webhook. Para obter detalhes sobre os campos do Webhook, consulte a tabela Parâmetros de webhooks abaixo.

verbose_logging

Tipo: booliano

Habilita o registro detalhado em coreapps. Esse nível de registro deve ser usado apenas para testes devido ao alto volume de saída. Se for definido como true, o atributo log_level será ignorado.


Valores:true, false (padrão)

log_level

Tipo: objeto webhooks

Configura o nível de registro em coreapps. Cada nível reduz gradualmente a quantidade de saída de registros: info tem o maior número de informações, enquanto fatal inclui somente erros críticos.


Valores:info (padrão), warning, error e fatal.

Parâmetros de webhooks

NomeDescrição

max_concurrent_requests

Tipo: número inteiro

Configura o número máximo de solicitações em andamento de retorno de chamada que são enviadas.


Valores:6 (padrão), 12, 18 ou 24.
Reinicialização obrigatória do Coreapp.

url

Tipo: string

As notificações de entrada e saída são roteadas para essa URL. Consulte a documentação sobre Webhooks para obter mais informações.


É necessário um ponto de extremidade baseado em HTTPS, já que HTTP não funcionará.
Exemplo:https://spotless-process.glitch.me/webhook.

message

Tipo: objeto de mensagens

Disponível na v2.41.2 e mais recentes

Aninhado no objeto webhooks, permite que os clientes definam quais notificações de webhooks relacionadas a mensagens querem receber desta lista: sent, delivered e read. Saiba mais informações sobre os status aqui.


A empresa pode escolher se quer ou não receber as notificações de webhooks definindo os valores como true (padrão) ou false.

Parâmetros de mídia

NomeDescrição

auto_download

Tipo: matriz

Especifica quais tipos de mídia baixar automaticamente.


Valores:audio, document, voice, video, image e sticker.

Parâmetros do coletor de lixo

NomeDescrição

messages

Tipo: booliano

Configura a coleta de lixo de mensagens.


Valores:true (padrão), false.
Reinicialização obrigatória do Coreapp.

media

tipo: booliano

Configura a coleta de lixo de mídia.


Valores:true, false (padrão)
Reinicialização obrigatória do Coreapp.

Redefinir para as configurações-padrão

A fim de redefinir todas as configurações do app para os valores-padrão, envie uma solicitação DELETE para o ponto de extremidade /v1/settings/application.

Exemplo de solicitação

DELETE /v1/settings/application

Se bem-sucedida, a resposta retornará 200 OK com null ou {}.

Se houver algum erro, consulte Mensagens de erro e status.