API local de la Plataforma de WhatsApp Business

Estamos retirando la API local. Consulta nuestro documento Retirada de la API local para obtener más información y aprender a migrar a nuestra API de nube de nueva generación.

Configuración de la aplicación

Configuración de la aplicación para el cliente local de WhatsApp Business.

Requisitos

  • Las solicitudes se deben realizar con la cuenta admin.
  • Todas las respuestas deben incluir 200 OK HTTPS.

Lectura

Obtén la configuración actual de la aplicación para el cliente local de WhatsApp Business.

Ejemplo

Envía una solicitud GET al extremo /v1/settings/application para obtener la configuración actual de la aplicación.

GET /v1/settings/application

Si se lleva a cabo correctamente, la respuesta contiene 200 OK y una carga útil JSON con un objeto application que muestra todas las opciones de configuración actuales de la aplicación y sus valores.

Ejemplo de respuesta

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

Perímetros

PerímetroDescripción

/media/providers

Utilízalo para administrar una lista de proveedores multimedia para enviar enlaces a contenido multimedia.

Actualización

Para actualizar la configuración de la aplicación, envía una solicitud PATCH al extremo /v1/settings/application con un objeto JSON que contenga los nombres de los campos y los valores que se deben establecer.

En el caso de las campañas de mensajes que involucran un gran volumen de mensajes, se recomienda desactivar la recolección automática de elementos no utilizados; para ello, se debe establecer garbagecollector_enable.messages en false. Una vez terminada la campaña, se puede volver a establecer en true para activarla de nuevo.

Para verificar si la recolección automática de elementos no utilizados está desactivada, puedes enviar una solicitud GET al extremo /v1/settings/application y leer la propiedad garbagecollector_enable.

Ejemplo de solicitud

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

Si se lleva a cabo correctamente, la respuesta contiene 200 OK con un valor null o un objeto JSON.

Si experimentas algún error, consulta Mensajes de error y de estado.

Parámetros

Algunas opciones de configuración requieren que la aplicación principal se reinicie para que los cambios se apliquen. Estas opciones de configuración son callback_persist, garbagecollector_enable, verbose_logging, log_level y webhooks.max_concurrent_requests.

“log_level”
NombreDescripción

axolotl_context_striping_disabled

Tipo: booleano

Afecta a los límites de conexión de la base de datos.


Rendimiento de salida y entrada mejorado con v2.25. Esta optimización depende de la creación de conexiones de base de datos adicionales. Para algunas implementaciones, puede provocar que se alcancen los límites de conexión de la base de datos. En ese caso, establece la opción axolotl_context_striping_disabled en true para desactivar esta función de mejora del rendimiento. No se produce ningún otro efecto en ninguna funcionalidad de la aplicación principal.


Valores:true, false (predeterminado)

Se requiere el reinicio de la aplicación principal.

callback_backoff_delay_ms

Tipo: cadena

Retraso del retroceso de una devolución de llamada errónea en milisegundos.


Esta opción se utiliza para configurar la cantidad de tiempo que se retrasa el retroceso antes de volver a intentar una devolución de llamada errónea. El retraso del retroceso aumenta de manera lineal por este valor cada vez que una devolución de llamada no logra obtener una respuesta HTTPS 200 OK. El retraso del retroceso está limitado por la opción de configuración max_callback_backoff_delay_ms. Por ejemplo, si una devolución de llamada no se realiza correctamente la primera vez, volverá a intentarla al cabo de 3000 ms (3 s). Un segundo error provocará un retraso de 6000 ms (6 s) antes del reintento. Esto es así sucesivamente hasta que la devolución de llamada se lleva a cabo correctamente o hasta que el retraso alcanza un valor de 900 000 ms (15 min), tras el cual la devolución de llamada se seguirá intentando sin que el retraso aumente.


Valor predeterminado: 3000

callback_persist

Tipo: booleano

Almacena las devoluciones de llamada en el disco hasta que el Webhook las confirma correctamente o las rechaza. Los mensajes y las devoluciones de llamada se almacenan en una base de datos local para garantizar que se entregan correctamente antes de eliminarse de dicha base de datos. De este modo, se protegen las devoluciones de llamada en caso de inactividad del servidor o el cliente de la API de WhatsApp Business.
Las notificaciones que no se entregan correctamente (sin respuesta HTTPS 200) se vuelven a intentar indefinidamente. Usa esta opción para configurar el reintento.


Valores:true (predeterminado), false
Se requiere el reinicio de la aplicación principal.

db_garbagecollector_enable

Tipo: booleano

Este campo se ha retirado a partir de la versión 2.49.


Activa la recolección automática de elementos no utilizados de la base de datos de mensajes para facilitar la administración de la base de datos.


Este parámetro es false para los usuarios que tenían pass_through establecido en false en versiones anteriores a v2.29. Se recomienda activar esta opción para garantizar el funcionamiento estable de la base de datos. Si quieres desactivar esta opción, te recomendamos que consideres la posibilidad de utilizar el extremo /services/message/gc para administrar la base de datos.


Valores:true (predeterminado), false

Se requiere el reinicio de la aplicación principal.

garbagecollector_enable

Tipo: objeto de recolección de elementos no utilizados

Activa la recolección automática de elementos no utilizados de los mensajes y el contenido multimedia.


Se recomienda la configuración de la recolección de elementos no utilizados de los mensajes y el contenido multimedia para asegurarse de que las filas y archivos antiguos o no usados se eliminen. Si se desactiva, el recolector de elementos no utilizados se puede iniciar mediante los extremos /services/message/gc y /services/media/gc. Consulta los valores en la tabla Parámetros del recolector de elementos no utilizados.


Se requiere el reinicio de la aplicación principal.

heartbeat_interval

Tipo: entero

Intervalo del nodo maestro de supervisión de los nodos de la aplicación principal en segundos.


Valor predeterminado: 5
Se aplica a configuraciones de conexión múltiple.

max_callback_backoff_delay_ms

Tipo: cadena

Retraso máximo de una devolución de llamada errónea en milisegundos. Para obtener más información, lee la descripción de callback_backoff_delay_ms a continuación.


Valor predeterminado: 900 000

media

Tipo: matriz

Lista de archivos multimedia que se van a descargar automáticamente. Consulta Configuración de archivos multimedia de descarga automática para obtener más información.

notify_user_change_number

Tipo: booleano

Afecta a la notificación del sistema user_changed_number.


Valores:true, false (predeterminado)

pass_through

Tipo: booleano

A partir de la versión 2.35, ya no se puede volver a activar la opción pass_through para los clientes de la API de WhatsApp Business.


Permite que los mensajes individuales se eliminen o almacenen en una base de datos local una vez entregados o leídos.


Cuando los mensajes se han enviado, se almacenan en una base de datos local. Esta base de datos se utiliza como el historial de la aplicación. Dado que la empresa mantiene su propio historial, puedes especificar si quieres enviar mensajes con el parámetro pass_through.

  • Si el valor es true, se eliminan los mensajes de la base de datos local una vez enviados o cuando el destinatario los ha leído.
  • Si el valor es false, los mensajes se guardan en el almacenamiento local hasta que se eliminan automáticamente (es decir, db_garbagecollector_enable es true) o de manera explícita (es decir, db_garbagecollector_enable es false). Para obtener más información, consulta la documentación de servicios.

Se recomienda desactivar el parámetro pass_through para que la devolución de llamada status pueda funcionar según lo previsto.


Valores:true, false (predeterminado)

Se requiere el reinicio de la aplicación principal.

show_security_notifications

Tipo: booleano

Si se activa, recibirás una notificación de webhook user_identity_changed cuando el cliente de la API de WhatsApp Business detecte que un usuario con el que mantienes una conversación puede haber cambiado. Si esto sucede, todos los mensajes salientes para este usuario se bloquearán hasta que confirmes el cambio de identidad mediante el extremo identity.


Valores:true, false (predeterminado)

skip_referral_media_download

Tipo: booleano

Si se establece en true, la imagen o el vídeo en que el usuario ha hecho clic en un anuncio de clic a WhatsApp no se descarga.


Valor predeterminado:false

unhealthy_interval

Tipo: entero

Cantidad máxima de segundos que un nodo maestro espera a que un nodo de la aplicación principal responda a un latido antes de considerarlo erróneo y de iniciar el proceso de conmutación por error.


Valor predeterminado: 30
Se aplica a configuraciones de conexión múltiple.

webhook_payload_conversation_pricingmodel_disabled

Tipo: booleano

Este campo se ha retirado a partir de la versión 2.39.

Controla la inclusión de las cargas útiles de información de conversaciones y precios en las notificaciones de estado de mensajes.


Valores:true, false (predeterminado)

No es necesario reiniciar la aplicación principal.

webhooks

Tipo: objeto de webhooks

Se requiere si se utilizan webhooks.

Proporciona la URL del webhook. Si la URL del webhook no está establecida, las devoluciones de llamada se pierden. Para descubrir una forma sencilla de ver y probar los webhooks, consulta Aplicación de prueba de ejemplo.


Para validar los eventos de webhook, puedes especificar un secreto compartido como parámetro de consulta al definir la URL del webhook. Ejemplo: https://url?auth='[shared_secret]'.

URL del webhook. Por ejemplo: https://spotless-process.glitch.me/webhook.


Si la URL del webhook no está establecida, las devoluciones de llamada se pierden. Las devoluciones de llamada son un canal importante para entregar notificaciones oportunas, así como errores del tipo fuera de banda, por lo que se recomienda encarecidamente configurar el extremo de la URL del webhook. Para obtener más información sobre los campos de webhooks, consulta la tabla Parámetros de webhooks a continuación.

verbose_logging

Tipo: booleano

Permite el registro detallado en las aplicaciones principales. Este nivel de registro solo se debe usar para pruebas debido al alto volumen de resultados. Si se establece en true, el atributo log_level se ignora.


Valores:true, false (predeterminado)

log_level

Tipo: objeto de webhooks

Configura el nivel de registro en las aplicaciones principales. Cada nivel reduce gradualmente la cantidad de registros generados. info contiene la mayor cantidad de información, mientras que fatal solo contiene los errores críticos.


Valores:info (predeterminado), warning, error y fatal.

Parámetros de webhooks

NombreDescripción

max_concurrent_requests

Tipo: entero

Permite configurar el número máximo de solicitudes de devolución de llamada en curso que se envían.


Valores:6 (predeterminado), 12, 18 o 24
Se requiere el reinicio de la aplicación principal.

url

Tipo: cadena

Las notificaciones entrantes y salientes se dirigen a esta URL. Para obtener más información, consulta la documentación de webhooks.


Se requiere un extremo basado en HTTPS; HTTP no funcionará.
Ejemplo:https://spotless-process.glitch.me/webhook

message

Tipo: objeto de mensajes

Disponible en la versión 2.41.2 y posteriores

Se anida en el objeto webhooks y permite a los clientes definir qué notificaciones de webhooks relacionadas con los mensajes quieren recibir de esta lista: sent, delivered o read. Puedes encontrar más información sobre estos estados aquí.


La empresa puede decidir si recibir estas notificaciones de webhooks; para ello, debe definir los valores como true (predeterminado) o false.

Parámetros de contenido multimedia

NombreDescripción

auto_download

Tipo: matriz

Permite especificar los tipos de contenido multimedia que se descargarán automáticamente.


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

Parámetros del recolector de elementos no utilizados

NombreDescripción

messages

Tipo: booleano

Configura la recolección de elementos no utilizados de los mensajes.


Valores:true (predeterminado), false
Se requiere el reinicio de la aplicación principal.

media

Tipo: booleano

Configura la recolección de elementos no utilizados del contenido multimedia.


Valores:true, false (predeterminado)
Se requiere el reinicio de la aplicación principal.

Restablecer la configuración predeterminada

Para restablecer todas las opciones de configuración de una aplicación a los valores predeterminados, envía una solicitud DELETE al extremo /v1/settings/application.

Ejemplo de solicitud

DELETE /v1/settings/application

Si se lleva a cabo correctamente, la respuesta contiene 200 OK con un valor null o {}.

Si experimentas algún error, consulta Mensajes de error y de estado.