API de administración de WhatsApp Business

Este documento se ha actualizado.
La traducción en Español (España) no está disponible todavía.

Actualización del documento en inglés: 11 sep.

WhatsApp Business Platform > Business Management API

Información general

La API de administración de WhatsApp Business te permite crear y administrar activos comerciales relacionados con WhatsApp, como cuentas de WhatsApp Business y plantillas de mensajes. La API se basa en la API de marketing y utiliza algunos de sus extremos, por lo que esta documentación puede incluir enlaces a la documentación de la API de marketing, si corresponde.

Requisitos

Una cuenta empresarial de Meta.
Una cuenta de WhatsApp Business asociada a tu cuenta empresarial de Meta.
Una aplicación empresarial asociada a tu cuenta empresarial de Meta.
Un identificador de acceso de usuario del sistema de integración empresarial, un identificador de acceso de usuario del sistema o un identificador de acceso de usuario.
El permiso whatsapp_business_management.
Si la aplicación accede a extremos que se dirigen a tu cuenta empresarial de Meta, necesitarás el permiso business_management.
Si la aplicación accede a los extremos de la API de nube, necesitarás el permiso whatsapp_business_messaging.

Identificadores de acceso

La plataforma admite los siguientes tipos de identificador de acceso. El tipo que uses depende de las personas que usarán la aplicación y de si eres proveedor de soluciones o no.

Si eres desarrollador directo, es decir, solo tú o tu empresa accederéis a vuestros datos, usa un identificador de acceso de usuario del sistema.
Si eres proveedor de tecnología, usa un identificador de acceso de usuario del sistema de integración empresarial.
Si eres socio de soluciones, usa identificadores de acceso de usuario del sistema para compartir tu línea de crédito con los clientes recién incorporados e identificadores de acceso de usuario del sistema de integración empresarial para el resto.

Identificadores de acceso de usuario del sistema

Los identificadores de acceso de usuario del sistema te representan a ti, a tu empresa u organización, o a las personas de tu empresa u organización. La principal ventaja de estos identificadores es que no caducan y pueden representar servicios automatizados de tu empresa que no necesiten entradas de los usuarios.

Los identificadores de acceso de usuario del sistema son el único tipo de identificador que pueden usar los socios de soluciones para compartir líneas de crédito con los clientes incorporados.

Para poder generar un identificador de acceso de usuario del sistema, debes crear un usuario del sistema. La mayoría de los extremos comprueban si el usuario identificado por el identificador tiene acceso al recurso que se ha consultado. Si no tiene acceso al recurso, la solicitud se rechazará con el código de error 200.

Los usuarios del sistema pueden ser empleados o administradores.

Usuarios empleados del sistema

Debes conceder acceso a los usuarios empleados del sistema a las cuentas específicas de WhatsApp Business que sean propiedad de la empresa de Meta o se hayan compartido con ella. Si la aplicación solo necesitará acceso a algunas de tus cuentas de WhatsApp Business, un usuario empleado del sistema será suficiente.

Una vez creado, debes conceder acceso parcial o total a los activos comerciales para cada cuenta de WhatsApp Business a la que tenga que acceder el usuario del sistema.

Usuarios administradores del sistema

De forma predeterminada, los usuarios administradores del sistema tienen acceso total a las cuentas de WhatsApp Business y a los recursos que sean de tu propiedad o de la empresa o que se hayan compartido contigo o con la empresa.

Los usuarios administradores del sistema resultan útiles si la aplicación necesita acceder a cuentas de WhatsApp Business que se han compartido recientemente con tu empresa; si utilizas un usuario empleado del sistema, debes conceder acceso a los activos comerciales manualmente para todas las cuentas de WhatsApp Business que se hayan compartido contigo.

Ten en cuenta que puedes anular el acceso predeterminado de un usuario administrador del sistema a activos comerciales si concedes acceso parcial a cada cuenta de WhatsApp Business. Consulta Acceso a los activos comerciales para obtener más información sobre cómo configurar y anular el acceso.

Crear usuarios del sistema

Para crear un usuario del sistema, haz lo siguiente:

Inicia sesión en Meta Business Suite.
Localiza la cuenta empresarial en el menú desplegable de la parte superior izquierda y haz clic en el icono Configuración (engranaje).
Haz clic en Configuración de la empresa.
Ve a Usuarios > Usuarios del sistema.
Haz clic en el botón Añadir y crea un usuario administrador o empleado del sistema.

Generar identificadores de acceso de usuario del sistema

Para generar un identificador de acceso de usuario del sistema después de crear un usuario del sistema, haz lo siguiente:

Inicia sesión en Meta Business Suite.
Localiza la cuenta empresarial en el menú desplegable de la parte superior izquierda y haz clic en el icono Configuración (engranaje).
Haz clic en Configuración de la empresa.
Ve a Usuario > Usuarios del sistema.
Selecciona el usuario del sistema adecuado de la lista de usuarios del sistema.
Haz clic en el botón Generar un identificador nuevo.
Selecciona la aplicación que usará el identificador.
Selecciona los permisos de la API Graph que necesite la aplicación para funcionar correctamente y genera el identificador.

Identificadores de acceso de usuario del sistema de integración empresarial

Los identificadores de acceso de usuario del sistema de integración empresarial son específicos de los clientes individuales incorporados y deben usarlos los proveedores de tecnología y los socios de soluciones al acceder a los datos de los clientes incorporados.

Estos identificadores son útiles para las aplicaciones que llevan a cabo acciones automatizadas mediante programación en las cuentas de WhatsApp Business de los clientes sin tener que depender de la entrada de los usuarios de la aplicación o sin que sea necesario volver a autenticarse en el futuro.

Para generar identificadores de acceso de usuario del sistema de integración empresarial, tienes que implementar el registro insertado (configurado con el inicio de sesión con Facebook para empresas) e intercambiar el código que se te devuelve cuando un cliente completa el proceso.

Consulta los documentos Registro insertado e Identificadores de acceso de usuario del sistema de integración empresarial para obtener más información sobre estos identificadores y cómo se generan.

Identificadores de acceso de usuario

Aunque los identificadores de acceso de usuario se admiten y pueden usarlos todos los desarrolladores de aplicaciones, probablemente solo los utilizarás cuando utilices el panel de aplicaciones por primera vez para enviar tu primer mensaje de prueba. Sin embargo, a medida que desarrolles la aplicación, es probable que cambies a un identificador de acceso de usuario del sistema (y, finalmente, a un identificador de acceso de usuario del sistema empresarial si eres proveedor de tecnología o proveedor de soluciones). Esto se debe a que los identificadores de acceso de usuario caducan rápidamente, por lo que debes generar uno nuevo cada pocas horas.

Hay varias maneras de generar un identificador de acceso de usuario:

Accede al panel de aplicaciones > WhatsApp > ventana Configuración de la API. Siempre que accedes a esta ventana, se genera un identificador de acceso de usuario. De forma automática, el identificador se asigna a tu usuario, ya que tienes la sesión iniciada en tu cuenta de desarrollador al acceder a esta ventana.
Usa el explorador de la API Graph.
Implementa el inicio de sesión con Facebook.

Usar identificadores en las solicitudes

Al realizar solicitudes a la API, incluye el identificador en el encabezado de la solicitud de autorización precedido de Bearer. Por ejemplo:

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

Acceso a los activos comerciales

Después de crear un usuario del sistema, debes establecer los niveles de acceso a los activos comerciales. Muchos extremos requieren que el usuario del sistema cuyo identificador se haya incluido en las solicitudes de la API tenga acceso parcial o total a los activos comerciales de la cuenta de WhatsApp Business a la que se realiza la consulta (o a sus recursos). Si el usuario del sistema no tiene este acceso, los extremos devolverán el código de error 200.

Ten en cuenta que si estableces el acceso de un usuario del sistema a los activos comerciales como parcial en una cuenta de WhatsApp Business, puedes restringir aún más el acceso a determinados activos o acciones en la cuenta de WhatsApp Business. Por ejemplo, si tienes una gran empresa y quieres que un determinado departamento solo tenga acceso de lectura a la plantilla y la información del número de teléfono de empresa de una cuenta de WhatsApp Business, puedes crear un usuario del sistema para ese departamento y definir únicamente acceso detallado de visualización para dichos datos.

Para configurar el acceso a los activos comerciales en una cuenta de WhatsApp Business:

Inicia sesión en Meta Business Suite.
Localiza la cuenta empresarial en el menú desplegable de la parte superior izquierda y haz clic en el icono Configuración (engranaje).
Ve a Cuentas > Cuentas de WhatsApp.
Selecciona la cuenta de WhatsApp Business correspondiente.
Selecciona la pestaña Acceso de la cuenta de WhatsApp.
Haz clic en el botón +Añadir personas.
Selecciona el usuario del sistema correspondiente y asigna los niveles de acceso adecuados en la cuenta de WhatsApp Business.

Probar extremos

Te recomendamos usar nuestra colección de Postman o cURL al probar los extremos. Aunque puedes usar el explorador de la API Graph, este utiliza un método que no recomendamos que consiste en pasar los identificadores como parámetros de la cadena de consulta. En su lugar, puedes pasar los identificadores en encabezados de solicitud.

Obtener información sobre una empresa

Para obtener información sobre una empresa, envía una solicitud GET al extremo WhatsAppBusinessAccount (el valor de <WHATSAPP_BUSINESS_ACCOUNT_ID> es el identificador de tu cuenta de WhatsApp Business).

Ejemplo de solicitud

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Ejemplo de respuesta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

Para obtener información específica sobre una empresa, como el nombre, las plantillas de mensajes y los números de teléfono, envía una solicitud GET al extremo WhatsAppBusinessAccount (el valor de <WHATSAPP_BUSINESS_ACCOUNT_ID> es el identificador de tu cuenta de WhatsApp Business) y define el valor del parámetro fields como una lista de elementos que quieres que se devuelvan.

Ejemplo de solicitud

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Ejemplo de respuesta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

Límites de frecuencia

Las solicitudes que realiza la aplicación a la API de administración de WhatsApp Business se incluyen en el recuento de la aplicación. El recuento de llamadas de una aplicación es el número de llamadas que esta puede realizar durante un periodo renovable de una hora. En el caso de la siguiente API de administración de WhatsApp Business, la aplicación puede realizar de forma predeterminada 200 llamadas por hora, por aplicación, por cuenta de WhatsApp Business (WABA). En el caso de las cuentas WABA activas con al menos un número de teléfono registrado, la aplicación puede realizar 5000 llamadas por hora, por aplicación, por cuenta WABA activa.

Tipo de llamada	Extremo
`GET`	`/{whatsapp-business-account-id}`
`GET`, `POST` y `DELETE`	`/{whatsapp-business-account-id}/assigned_users`
`GET`	`/{whatsapp-business-account-id}/phone_numbers`
`GET`, `POST` y `DELETE`	`/{whatsapp-business-account-id}/message_templates`
`GET`, `POST` y `DELETE`	`/{whatsapp-business-account-id}/subscribed_apps`
`GET`	`/{whatsapp-business-account-to-number-current-status-id}`

En el caso de las siguientes API de línea de crédito, la aplicación puede hacer 5000 llamadas por hora, por aplicación.

Tipo de llamada	Extremo
`GET`	`/{business-id}/extendedcredits`
`POST`	`/{extended-credit-id}/whatsapp_credit_sharing_and_attach`
`GET` y `DELETE`	`/{allocation-config-id}`
`GET`	`/{extended-credit-id}/owning_credit_allocation_configs`

A fin de evitar alcanzar los límites de frecuencia, recomendamos usar webhooks para hacer un seguimiento de las actualizaciones de estado de las plantillas de mensajes, los números de teléfono y las cuentas WABA.

Si necesitas más detalles sobre cómo obtener información del uso de la frecuencia actual, consulta Encabezados.

Más información

SDK de Facebook: para solicitar permisos a los usuarios mediante el inicio de sesión con Facebook, puedes implementar uno de nuestros SDK.
API de marketing (Business Manager): obtén más información sobre la API de marketing (Business Manager).
Revisión de la aplicación: obtén más información sobre el proceso para acceder a tus datos o a los datos que pertenecen a otros usuarios.
Puedes ver un vídeo sobre la configuración de la Plataforma de WhatsApp Business.

Siguientes pasos

Guías: obtén más información sobre otras acciones que puedes llevar a cabo con la API de administración de WhatsApp Business.
Explora nuestra colección de Postman

Plataforma de WhatsApp Business | API de nube | API local | API de administración de WhatsApp Business