La traducción en español no está disponible todavía.
Información general
La API de administración comercial 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 punto de conexión, por lo que esta documentación puede contener enlaces a la documentación de la API de marketing cuando corresponda.
Requisitos
- Una cuenta comercial de Meta.
- Una cuenta de WhatsApp Business asociada con tu cuenta comercial de Meta.
- Una app de negocios asociada con tu cuenta comercial de Meta.
- El permiso whatsapp_business_management.
- Si tu app accede a los puntos de conexión dirigidos a tu cuenta comercial de Meta, necesitarás el permiso business_management.
- Si tu app accede a los puntos de conexión de la API de la nube, necesitarás el permiso whatsapp_business_messaging.
Tokens de acceso
La plataforma admite los siguientes tipos de token de acceso. El tipo que uses dependerá de quién va a usar tu app y si eres o no un proveedor de soluciones.
- Si eres un desarrollador directo, es decir, si solo tu empresa o tú accederán a tus propios datos, usa un token de acceso de usuario del sistema.
- Si eres un proveedor de tecnología, usa un token de acceso de usuario del sistema de integración comercial.
- Si eres un socio de soluciones, usa tokens de acceso de usuario del sistema para compartir tu línea de crédito con los clientes que se acaban de registrar y tokens de acceso de usuario del sistema de integración comercial en el resto de los casos.
Token de acceso del usuario del sistema
Los tokens de acceso de usuario del sistema te representan a ti, a tu empresa u organización, o a personas que pertenecen a estas. La ventaja principal de estos tokens es que no caducan y que pueden representar servicios automatizados dentro de tu empresa, que no requieren entradas del usuario.
Los tokens de acceso de usuario del sistema son el único tipo de token que pueden usar los socios de soluciones para compartir líneas de crédito con los clientes que se registraron.
Antes de generar un token de acceso de usuario del sistema, debes crear un usuario del sistema. La mayoría de los puntos de conexión verifican si el usuario que identificó el token tiene acceso al recurso solicitado. Si el usuario no tiene acceso al recurso, se rechazará la solicitud y se mostrará el código de error 200.
Los usuarios del sistema pueden ser empleados o administradores.
Usuarios empleados del sistema
Los usuarios empleados del sistema pueden obtener acceso a determinadas cuentas de WhatsApp Business que son propiedad del negocio de Meta o que se comparten con este. Si tu app solo necesita acceso a tus propias cuentas de WhatsApp Business, un usuario empleado del sistema es suficiente.
Una vez que lo crees, deberás otorgar accesototal o parcial a cada cuenta de WhatsApp Business a la que el usuario del sistema necesita acceder.
Usuarios administradores del sistema
De manera predeterminada, los usuarios administradores del sistema tienen acceso total a todos los recursos y cuentas de WhatsApp Business tuyos o de tu empresa, o que se comparten contigo o tu empresa.
Los usuarios administradores del sistema son útiles si tu app necesita acceder a cuentas de WhatsApp Business que se compartieron por primera vez con tu empresa. Si usas un usuario empleado del sistema, debes otorgar manualmente acceso de activos a cada cuenta de WhatsApp Business que se comparte contigo.
Ten en cuenta que puedes anular el acceso predeterminado de un usuario administrador del sistema si otorgas acceso parcial de activos a cada cuenta de WhatsApp Business. Consulta Acceso a activos comerciales para aprender a configurar y anular el acceso.
Crear usuarios del sistema
Para crear un usuario del sistema:
- Inicia sesión en Meta Business Suite.
- Localiza tu cuenta comercial en el menú desplegable superior izquierdo y haz clic en el icono de configuración(engranaje).
- Haz clic en Configuración del negocio.
- Dirígete a Usuarios > Usuarios del sistema.
- Haz clic en el botón Agregar y crea un usuario del sistema de tipo administrador o empleado.
Generar tokens de acceso de usuario del sistema
Para generar un token 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 tu cuenta comercial en el menú desplegable superior izquierdo y haz clic en el icono de configuración(engranaje).
- Haz clic en Configuración del negocio.
- Dirígete a Usuario > Usuarios del sistema.
- Seleccione el usuario del sistema apropiado de la lista de usuarios del sistema.
- Haz clic en el botón Generar nuevo token.
- Selecciona la app que usará el token.
- Selecciona los permisos de la API Graph que la app necesita para funcionar correctamente y generar el token.
Tokens de acceso del usuario del sistema de integración comercial
Los tokens de acceso de usuario del sistema de integración comercial se extienden a clientes individuales registrados y los deben usar los proveedores de tecnología y socios de soluciones cuando acceden a los datos de los clientes registrados.
Estos tokens son útiles para las apps que realizan acciones programáticas y automatizadas en las cuentas de WhatsApp Business, ya que no se basan en entradas de los usuarios ni es necesario volver a autenticarlos en el futuro.
Para generar tokens de acceso de usuario del sistema de integración comercial, debes implementar el registro insertado (configurado con el inicio de sesión con Facebook para empresas) e intercambiar el código que se devuelve cuando un cliente completa el proceso.
Consulta los documentos Registro insertado y Tokens de acceso de usuario del sistema de integración comercial para obtener más información sobre estos tokens y cómo se generan.
Tokens de acceso del usuario
Si bien todos los desarrolladores de apps admiten y pueden usar los tokens de acceso de usuario, es probable que solo los utilices cuando uses por primera vez el panel de apps para enviar tu primer mensaje de prueba. Sin embargo, cuando desarrolles tu app, es muy posible que decidas usar un token de acceso de usuario del sistema (y tal vez un token de acceso de usuario del sistema comercial, si eres proveedor de tecnología o de soluciones). Esto se debe a que los tokens de acceso de usuario caducan rápidamente, por lo que tendrás que generar uno nuevo cada pocas horas.
Hay varias maneras de generar un token de acceso de usuario:
- Accede al Panel de apps > WhatsApp > Configuración de API. Este panel genera un nuevo token de acceso de usuario cada vez que lo visitas. El token se extiende automáticamente a tu usuario, ya que inicias sesión con tu cuenta de desarrollador cuando accedes al panel.
- Usa el explorador de la API Graph.
- Implementa el inicio de sesión con Facebook.
Usar tokens en solicitudes
Cuando realices solicitudes a la API, incluye tu token en un encabezado de solicitud de autorización, precedido por Bearer. Por ejemplo:
curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \ -H 'Authorization: Bearer EAAJB...' \
Acceso a activos comerciales
Después de crear un usuario del sistema, debes configurar niveles de acceso a activos comerciales. Muchos puntos de conexión requieren que el usuario cuyo token se incluye en las solicitudes a la API también obtenga acceso parcial o total a la cuenta de WhatsApp Business respecto de la que se hace la consulta (o a sus activos). Si el usuario del sistema no tiene este acceso, estos puntos de conexión devolverán el código de error 200.
Ten en cuenta que si configuras el acceso a activos comerciales por parte del usuario del sistema en una Cuenta de WhatsApp Business como parcial, puedes restringir el acceso a ciertos activos o acciones en la Cuenta de WhatsApp Business. Por ejemplo, si tienes una empresa grande y quieres que solo un departamento determinado tenga acceso de lectura a la plantilla y los datos de números de teléfono comerciales de una Cuenta de WhatsApp Business, puedes crear un usuario del sistema para ese departamento y configurar el acceso granular solo para lectura de esos datos.
Para configurar acceso a recursos comerciales en una Cuenta de WhatsApp Business, haz lo siguiente:
- Inicia sesión en Meta Business Suite.
- Localiza tu cuenta comercial en el menú desplegable superior izquierdo y haz clic en el icono de configuración (engranaje).
- Ve a Cuentas > Cuentas de WhatsApp.
- Selecciona la cuenta de WhatsApp Business apropiada.
- Selecciona la pestaña Acceso a la cuenta de WhatsApp.
- Haz clic en el botón +Agregar personas.
- Selecciona el usuario del sistema apropiado y asigna los niveles de acceso necesarios en la cuenta de WhatsApp Business.
Prueba de puntos de conexión
Te recomendamos usar nuestra colección de Postman o cURL cuando pruebes los puntos de conexión. Aunque puedes usar la herramienta de explorador de la API Graph, esta pasa los tokens como parámetros de cadenas de consulta, opción que desaconsejamos (como alternativa, pasa los tokens en los encabezados de solicitud).
Obtén información sobre un negocio
Para obtener información acerca de una empresa, envía una solicitud GET al punto de conexión WhatsAppBusinessAccount, donde <WHATSAPP_BUSINESS_ACCOUNT_ID> es tu identificador de la 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, plantillas de mensajes y números de teléfono, envía una solicitud GET al punto de conexión WhatsAppBusinessAccount, donde <WHATSAPP_BUSINESS_ACCOUNT_ID> es el identificador de tu cuenta de WhatsApp Business, y configura el parámetro fields en una lista de elementos que te gustaría 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
| Tipo de llamada | Punto de conexión |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
| Tipo de llamada | Punto de conexión |
|---|---|
|
|
|
|
|
|
|
|
Para obtener más información sobre cómo obtener el uso actual del límite, consulta Encabezados.
Más información
- SDK de Facebook: para pedir permisos a los usuarios usando el inicio de sesión con Facebook, puedes implementar uno de nuestros SDK.
- Administrador comercial de la API de marketing : obtén más información acerca del administrador comercial de la API de marketing.
- Revisión de apps: obtén más información sobre el proceso para acceder a tus propios datos o a los datos de terceros.
- Mira un video sobre cómo configurar la Plataforma de WhatsApp Business.
Próximos pasos
- Guías: descubre qué otras cosas puedes hacer con la API de administración de WhatsApp Business.
