WhatsApp Business Platform > On-Premises API > Reference

La API de instalaciones locales dejará de estar disponible. Consulta nuestro documento Fin de la API de instalaciones locales para conocer los detalles y descubrir cómo migrar a nuestra nueva generación de API de la nube.

Configuración de la app

La configuración de la app del cliente de instalaciones locales de la API de WhatsApp Business.

Requisitos

Se deben realizar las solicitudes mediante la cuenta admin.
Todas las respuestas deben incluir 200 OK HTTPS.

Leer

Obtén la configuración actual de la app del cliente de instalaciones locales de la API de WhatsApp Business.

Ejemplo

Envía una solicitud GET al punto de conexión /v1/settings/application para obtener la configuración de la app.

GET /v1/settings/application

Si la operación se realiza correctamente, la respuesta contiene 200 OK y una carga JSON que incluye un objeto application en el que aparecen la configuración actual de la app 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ímetro	Descripción
`/media/providers`	Se utiliza para administrar una lista de proveedores de contenido multimedia y enviar enlaces con este tipo de contenido.

Actualizar

Para actualizar la configuración de la app, envía una solicitud PATCH al punto de conexión /v1/settings/application con un objeto JSON que contenga los nombres de los campos y los valores que se desean configurar.

Para las campañas de mensajes que involucran un gran volumen de mensajes, se recomienda desactivar la recolección automática de elementos no utilizados ajustando garbagecollector_enable.messages a false, y volviéndola a activar después de que termine la campaña, configurándola en true.

Puede verificar si la recolección automática de elementos no utilizados está desactivada enviando una solicitud GET a al punto de conexión /v1/settings/application y leyendo 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 la solicitud se envía correctamente, la respuesta contiene 200 OK con un objeto null o JSON.

En caso de que ocurra un error, consulta los Mensajes de error y de estado.

Parámetros

Algunas opciones requieren reiniciar la app principal para que se apliquen los cambios. Esas opciones son callback_persist, garbagecollector_enable, verbose_logging, log_level y webhooks.max_concurrent_requests.

`log_level`

Nombre Descripción

Nombre	Descripción
`axolotl_context_striping_disabled` Tipo: booleano	Afecta los límites de la conexión de la base de datos. El rendimiento de salida y entrada mejora con la `v2.25`. Esta optimización crea conexiones adicionales a la base de datos. En algunas implementaciones, se pueden alcanzar los límites de conexión de la base de datos. Si es así, define la configuración `axolotl_context_striping_disabled` en `true` para desactivar esta función de mejora del rendimiento. No se verán afectadas las otras funcionalidades de la app principal. Valores:`true`, `false` (predeterminado) Es necesario reiniciar la aplicación principal.
`callback_backoff_delay_ms` Tipo: cadena	Demora de retroceso de una devolución de llamada con error, en milisegundos. Se utiliza esta configuración para establecer el tiempo que demora el retroceso en volver a intentar una devolución de llamada con error. Esta demora aumenta de forma lineal en función de este valor cada vez que una devolución de llamada no recibe una respuesta `HTTPS 200 OK`. La opción `max_callback_backoff_delay_ms` asigna un límite a la demora de la interrupción de devolución de llamada. Por ejemplo, si una devolución de llamada falla una vez, se vuelve a intentar después de 3.000 ms (3 segundos). Un segundo error genera una demora de 6.000 ms (6 segundos) antes del próximo intento. Esto se repite hasta que la devolución de llamada es satisfactoria o hasta que la demora llega a 900.000 ms (15 minutos). A partir de ese momento, se sigue intentando realizar la devolución de llamada, pero la demora deja de aumentar. Opción predeterminada: 3.000
`callback_persist` Tipo: booleano	Almacena las devoluciones de llamada en el disco hasta que el webhook las reconozca correctamente o no. Los mensajes y las devoluciones de llamada se almacenan en una base de datos local a fin de garantizar su entrega correcta y luego se eliminan de esta base de datos. De esta manera, se protegen las devoluciones de llamada en caso de que el cliente de la API de WhatsApp Business o el servidor fallen. Las notificaciones que no se envían correctamente (no tienen una respuesta `HTTPS 200`) se vuelven a enviar indefinidamente. Usa esta opción para configurar la cantidad de reintentos. Valores:`true` (predeterminado), `false` Es necesario reiniciar la aplicación principal.
`db_garbagecollector_enable` Tipo: booleano	Este campo quedó obsoleto con la versión 2.49. Permite la recolección automática de elementos no deseados en la base de datos de mensajes para brindar asistencia a la hora de administrar bases de datos. Este parámetro es `false` para los usuarios que configuraron `pass_through` en `false` antes de la `v2.29`. Te recomendamos activar esta configuración para asegurarte de que tu base de datos funcione de manera estable. Si deseas desactivarla, recomendamos que consideres usar el punto de conexión `/services/message/gc` para administrar la base de datos. Valores:`true` (predeterminado), `false` Es necesario reiniciar la aplicación principal.
`garbagecollector_enable` Tipo: objeto recolector de elementos no utilizados	Permite la recolección automática de elementos no utilizados en los mensajes y en el contenido multimedia. Se recomienda la configuración de recolección automática de elementos no utilizados en los mensajes y en el contenido multimedia para asegurarse de que se eliminen las filas y archivos antiguos o no usados. Si esta opción está desactivada, es posible que el recolector automático de elementos no utilizados se inicie usando los puntos de conexión `/services/message/gc` y `/services/media/gc`. Consulta la tabla de los parámetros del recolector de elementos no utilizados para obtener información respecto de los valores. Es necesario reiniciar la aplicación principal.
`heartbeat_interval` Tipo: entero	Intervalo en segundos de la supervisión de los nodos de la app principal por parte del nodo maestro. Opción predeterminada: 5 Se aplica a configuraciones de conexión múltiple.
`max_callback_backoff_delay_ms` Tipo: cadena	Demora máxima para una devolución de llamada con error, en milisegundos. Para obtener más información, lee la descripción de `callback_backoff_delay_ms` a continuación. Opción predeterminada: 900.000
`media` Tipo: matriz	Lista de elementos multimedia por descargar automáticamente. Consulta Configuración de elementos multimedia de descarga automática para obtener más información.
`notify_user_change_number` Tipo: booleano	Afecta la notificación del sistema `user_changed_number`. Valores:`true`, `false` (predeterminado)
`pass_through` Tipo: booleano	A partir de la versión 2.35, no se puede volver a activar más la configuración `pass_through` para los clientes de la API de WhatsApp Business. Permite la eliminación de mensajes individuales de una base de datos o el almacenamiento de estos en ella después de su entrega o lectura. Cuando los mensajes se envían, se almacenan en una base de datos local. Esta base de datos se usa como historial de la app. Como la empresa mantiene su propio historial, puedes especificar si deseas `pass_through` o no. Cuando el valor es `true`, elimina los mensajes de la base de datos local una vez que el destinatario los recibe o los lee. Cuando el valor es `false`, guarda todos los mensajes en el medio de almacenamiento local hasta que se borran de forma automática (es decir, `db_garbagecollector_enable` es `true`) o explícita (es decir, `db_garbagecollector_enable` es `false`). Consulta la documentación Servicios para obtener más información. Te recomendamos activar `pass_through` para que la devolución de llamada `status` pueda funcionar como se espera. Valores:`true`, `false` (predeterminado) Es necesario reiniciar la aplicación principal.
`show_security_notifications` Tipo: booleano	Si están activadas, recibirás una notificación de webhook `user_identity_changed` cuando el cliente de la API de WhatsApp Business detecte que es probable que haya cambiado un usuario con el cual estás en una conversación. Cuando esto suceda, todos los mensajes salientes de ese usuario se bloquearán hasta que confirmes el cambio de identidad para este usuario con el punto de conexión `identity`. Valores:`true`, `false` (predeterminado)
`skip_referral_media_download` Tipo: booleano	Si está configurado en `true`, el video o la imagen en el que el usuario hace clic en un anuncio de clic a WhatsApp no se descarga. Valor predeterminado:`false`
`unhealthy_interval` Tipo: entero	La cantidad máxima de segundos que espera un nodo maestro para que un nodo de la app principal responda a una actividad antes de considerar que tiene un problema e iniciar el proceso de error. Opción predeterminada: 30 Se aplica a configuraciones de conexión múltiple.
`webhook_payload_conversation_pricingmodel_disabled` Tipo: booleano	Este campo quedó obsoleto con la versión 2.39. Controla la inclusión de cargas de información de las conversaciones y de los precios en las notificaciones de estados de mensajes. Valores:`true`, `false` (predeterminado) No es necesario reiniciar la app principal.
`webhooks` Tipo: objeto de Webhooks	Obligatorio cuando usas webhooks. Proporciona la URL del webhook. Si no se configura la URL del webhook, se interrumpen las devoluciones de llamadas. Consulta App de prueba de ejemplos para obtener información sobre cómo ver y probar tus webhooks de manera sencilla. Puedes validar eventos del webhook si se especifica un secreto compartido como parámetro de consulta cuando configuras la URL del webhook. Ejemplo: `https://url?auth='[shared_secret]'`. La URL del webhook. Por ejemplo: `https://spotless-process.glitch.me/webhook`. Si la URL del webhook no está configurada, se descartan las devoluciones de llamada. Las devoluciones de llamadas son un canal importante para entregar notificaciones oportunas y errores fuera de banda. Por lo tanto, se recomienda configurar el punto de conexión de la URL del webhook. Para obtener detalles sobre los campos de webhooks, consulta a continuación la tabla Parámetros de webhooks.
`verbose_logging` Tipo: booleano	Permite un inicio de sesión detallado en las apps principales. Este nivel de registro deberá usarse solo para las pruebas debido al alto volumen de salida. Si se configura en `true`, se ignora el atributo `log_level`. Valores:`true`, `false` (predeterminado)
`log_level` Tipo: objeto de Webhooks	Configura el nivel de inicio de sesión en las apps principales. Los niveles reducen de manera gradual la cantidad de salidas del registro: `info` tiene la mayor cantidad de información, mientras que `fatal` solo contiene errores críticos. Valores:`info` (predeterminado), `warning`, `error` y `fatal`

axolotl_context_striping_disabled

Tipo: booleano

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

El rendimiento de salida y entrada mejora con la v2.25. Esta optimización crea conexiones adicionales a la base de datos. En algunas implementaciones, se pueden alcanzar los límites de conexión de la base de datos. Si es así, define la configuración axolotl_context_striping_disabled en true para desactivar esta función de mejora del rendimiento. No se verán afectadas las otras funcionalidades de la app principal.

Valores:true, false (predeterminado)

Es necesario reiniciar la aplicación principal.

callback_backoff_delay_ms

Tipo: cadena

Demora de retroceso de una devolución de llamada con error, en milisegundos.

Se utiliza esta configuración para establecer el tiempo que demora el retroceso en volver a intentar una devolución de llamada con error. Esta demora aumenta de forma lineal en función de este valor cada vez que una devolución de llamada no recibe una respuesta HTTPS 200 OK. La opción max_callback_backoff_delay_ms asigna un límite a la demora de la interrupción de devolución de llamada. Por ejemplo, si una devolución de llamada falla una vez, se vuelve a intentar después de 3.000 ms (3 segundos). Un segundo error genera una demora de 6.000 ms (6 segundos) antes del próximo intento. Esto se repite hasta que la devolución de llamada es satisfactoria o hasta que la demora llega a 900.000 ms (15 minutos). A partir de ese momento, se sigue intentando realizar la devolución de llamada, pero la demora deja de aumentar.

Opción predeterminada: 3.000

callback_persist

Tipo: booleano

Almacena las devoluciones de llamada en el disco hasta que el webhook las reconozca correctamente o no. Los mensajes y las devoluciones de llamada se almacenan en una base de datos local a fin de garantizar su entrega correcta y luego se eliminan de esta base de datos. De esta manera, se protegen las devoluciones de llamada en caso de que el cliente de la API de WhatsApp Business o el servidor fallen.
Las notificaciones que no se envían correctamente (no tienen una respuesta HTTPS 200) se vuelven a enviar indefinidamente. Usa esta opción para configurar la cantidad de reintentos.

Valores:true (predeterminado), false
Es necesario reiniciar la aplicación principal.

db_garbagecollector_enable

Tipo: booleano

Este campo quedó obsoleto con la versión 2.49.

Permite la recolección automática de elementos no deseados en la base de datos de mensajes para brindar asistencia a la hora de administrar bases de datos.

Este parámetro es false para los usuarios que configuraron pass_through en false antes de la v2.29. Te recomendamos activar esta configuración para asegurarte de que tu base de datos funcione de manera estable. Si deseas desactivarla, recomendamos que consideres usar el punto de conexión /services/message/gc para administrar la base de datos.

Valores:true (predeterminado), false

Es necesario reiniciar la aplicación principal.

garbagecollector_enable

Tipo: objeto recolector de elementos no utilizados

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

Se recomienda la configuración de recolección automática de elementos no utilizados en los mensajes y en el contenido multimedia para asegurarse de que se eliminen las filas y archivos antiguos o no usados. Si esta opción está desactivada, es posible que el recolector automático de elementos no utilizados se inicie usando los puntos de conexión /services/message/gc y /services/media/gc. Consulta la tabla de los parámetros del recolector de elementos no utilizados para obtener información respecto de los valores.

Es necesario reiniciar la aplicación principal.

heartbeat_interval

Tipo: entero

Intervalo en segundos de la supervisión de los nodos de la app principal por parte del nodo maestro.

Opción predeterminada: 5
Se aplica a configuraciones de conexión múltiple.

max_callback_backoff_delay_ms

Tipo: cadena

Demora máxima para una devolución de llamada con error, en milisegundos. Para obtener más información, lee la descripción de callback_backoff_delay_ms a continuación.

Opción predeterminada: 900.000

media

Tipo: matriz

Lista de elementos multimedia por descargar automáticamente. Consulta Configuración de elementos multimedia de descarga automática para obtener más información.

notify_user_change_number

Tipo: booleano

Afecta la notificación del sistema user_changed_number.

Valores:true, false (predeterminado)

pass_through

Tipo: booleano

A partir de la versión 2.35, no se puede volver a activar más la configuración pass_through para los clientes de la API de WhatsApp Business.

Permite la eliminación de mensajes individuales de una base de datos o el almacenamiento de estos en ella después de su entrega o lectura.

Cuando los mensajes se envían, se almacenan en una base de datos local. Esta base de datos se usa como historial de la app. Como la empresa mantiene su propio historial, puedes especificar si deseas pass_through o no.

Cuando el valor es true, elimina los mensajes de la base de datos local una vez que el destinatario los recibe o los lee.
Cuando el valor es false, guarda todos los mensajes en el medio de almacenamiento local hasta que se borran de forma automática (es decir, db_garbagecollector_enable es true) o explícita (es decir, db_garbagecollector_enable es false). Consulta la documentación Servicios para obtener más información.

Te recomendamos activar pass_through para que la devolución de llamada status pueda funcionar como se espera.

Valores:true, false (predeterminado)

Es necesario reiniciar la aplicación principal.

show_security_notifications

Tipo: booleano

Si están activadas, recibirás una notificación de webhook user_identity_changed cuando el cliente de la API de WhatsApp Business detecte que es probable que haya cambiado un usuario con el cual estás en una conversación. Cuando esto suceda, todos los mensajes salientes de ese usuario se bloquearán hasta que confirmes el cambio de identidad para este usuario con el punto de conexión identity.

Valores:true, false (predeterminado)

skip_referral_media_download

Tipo: booleano

Si está configurado en true, el video o la imagen en el que el usuario hace clic en un anuncio de clic a WhatsApp no se descarga.

Valor predeterminado:false

unhealthy_interval

Tipo: entero

La cantidad máxima de segundos que espera un nodo maestro para que un nodo de la app principal responda a una actividad antes de considerar que tiene un problema e iniciar el proceso de error.

Opción predeterminada: 30
Se aplica a configuraciones de conexión múltiple.

webhook_payload_conversation_pricingmodel_disabled

Tipo: booleano

Este campo quedó obsoleto con la versión 2.39.

Controla la inclusión de cargas de información de las conversaciones y de los precios en las notificaciones de estados de mensajes.

Valores:true, false (predeterminado)

No es necesario reiniciar la app principal.

webhooks

Tipo: objeto de Webhooks

Obligatorio cuando usas webhooks.

Proporciona la URL del webhook. Si no se configura la URL del webhook, se interrumpen las devoluciones de llamadas. Consulta App de prueba de ejemplos para obtener información sobre cómo ver y probar tus webhooks de manera sencilla.

Puedes validar eventos del webhook si se especifica un secreto compartido como parámetro de consulta cuando configuras la URL del webhook. Ejemplo: https://url?auth='[shared_secret]'.

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

Si la URL del webhook no está configurada, se descartan las devoluciones de llamada. Las devoluciones de llamadas son un canal importante para entregar notificaciones oportunas y errores fuera de banda. Por lo tanto, se recomienda configurar el punto de conexión de la URL del webhook. Para obtener detalles sobre los campos de webhooks, consulta a continuación la tabla Parámetros de webhooks.

verbose_logging

Tipo: booleano

Permite un inicio de sesión detallado en las apps principales. Este nivel de registro deberá usarse solo para las pruebas debido al alto volumen de salida. Si se configura en true, se ignora el atributo log_level.

Valores:true, false (predeterminado)

log_level

Tipo: objeto de Webhooks

Configura el nivel de inicio de sesión en las apps principales. Los niveles reducen de manera gradual la cantidad de salidas del registro: info tiene la mayor cantidad de información, mientras que fatal solo contiene errores críticos.

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

Parámetros de Webhooks

Nombre Descripción

Nombre	Descripción
`max_concurrent_requests` Tipo: entero	Configura la cantidad máxima de solicitudes de devolución de llamada activas que se envían. Valores:`6` (predeterminado), `12`, `18` o `24` Es necesario reiniciar la app principal.
`url` Tipo: cadena	Las notificaciones entrantes y salientes se direccionan hacia esta URL. Consulta la documentación sobre Webhooks para obtener más información. Se necesita un punto de conexión basado en HTTPS; no funciona con HTTP. Ejemplo:`https://spotless-process.glitch.me/webhook`
`message` Tipo: objeto de mensajes Disponible en la versión 2.41.2 y posteriores	Si está anidada dentro del objeto `webhooks`, les permite a los clientes configurar qué mensajes vinculados a las notificaciones de webhooks desean recibir de la lista: `sent`, `delivered` y `read`. Obtén más información sobre los estados aquí. La empresa puede elegir si recibir estas notificaciones de webhooks o no configurando los valores en `true` (opción predeterminada) o `false`.

max_concurrent_requests

Tipo: entero

Configura la cantidad máxima de solicitudes de devolución de llamada activas que se envían.

Valores:6 (predeterminado), 12, 18 o 24
Es necesario reiniciar la app principal.

url

Tipo: cadena

Las notificaciones entrantes y salientes se direccionan hacia esta URL. Consulta la documentación sobre Webhooks para obtener más información.

Se necesita un punto de conexión basado en HTTPS; no funciona con HTTP.
Ejemplo:https://spotless-process.glitch.me/webhook

message

Tipo: objeto de mensajes

Disponible en la versión 2.41.2 y posteriores

Si está anidada dentro del objeto webhooks, les permite a los clientes configurar qué mensajes vinculados a las notificaciones de webhooks desean recibir de la lista: sent, delivered y read. Obtén más información sobre los estados aquí.

La empresa puede elegir si recibir estas notificaciones de webhooks o no configurando los valores en true (opción predeterminada) o false.

Parámetros de contenido multimedia

Nombre Descripción

Nombre	Descripción
`auto_download` Tipo: matriz	Especifica qué tipos de archivos multimedia se descargan automáticamente. Valores:`audio`, `document`, `voice`, `video`, `image`, `sticker`

auto_download

Tipo: matriz

Especifica qué tipos de archivos multimedia se descargan automáticamente.

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

Parámetros del recolector de elementos no utilizados

Nombre Descripción

Nombre	Descripción
`messages` Tipo: booleano	Configura los mensajes del recolector de elementos no utilizados en los mensajes. Valores:`true` (predeterminado), `false` Es necesario reiniciar la aplicación principal.
`media` Tipo: booleano	Configura el recolector de elementos no utilizados en el contenido multimedia. Valores:`true`, `false` (predeterminado) Es necesario reiniciar la app principal.

messages

Tipo: booleano

Configura los mensajes del recolector de elementos no utilizados en los mensajes.

Valores:true (predeterminado), false
Es necesario reiniciar la aplicación principal.

media

Tipo: booleano

Configura el recolector de elementos no utilizados en el contenido multimedia.

Valores:true, false (predeterminado)
Es necesario reiniciar la app principal.

Restablecer la configuración predeterminada

A fin de restablecer la configuración de la app a los valores predeterminados, envía una solicitud DELETE al punto de conexión /v1/settings/application.

Ejemplo de solicitud

DELETE /v1/settings/application

Si la solicitud se envía correctamente, la respuesta contiene 200 OK con null o {}.

En caso de que ocurra un error, consulta los Mensajes de error y de estado.