En Zenvia Customer Cloud, la funcionalidad Llamada a API permite integrar sistemas externos con su chatbot. Con ella, puede:
- Consultar datos de clientes en un CRM.
- Enviar información a sistemas externos.
- Automatizar acciones basadas en datos dinámicos.
Una API (Interfaz de Programación de Aplicaciones) es el medio mediante el cual diferentes sistemas se comunican entre sí.
Cómo acceder
En el Constructor del bot:
- Haga clic en los tres puntos del bloque (o en cualquier área del bloque).
- Haga clic en Agregar contenido.
- Seleccione Llamada a API.
Cómo configurar una Llamada a API
Complete los siguientes campos:
- Método: GET, POST, PUT, DELETE o PATCH.
- URL: endpoint de la API.
- Encabezado: (ej.: Authorization, Content-Type).
- Cuerpo: según el formato esperado (ej.: JSON).
¿Por qué usar otro bloque?
La ejecución de los bloques sigue este orden:
- Envía el mensaje;
- Recibe mensajes;
- Guarda variables;
- Ejecuta acciones (incluidas las llamadas a API);
- Define el siguiente flujo.
Esto significa que la respuesta de la API solo estará disponible después de que el bloque termine de ejecutarse. Necesita un nuevo bloque para utilizar los datos devueltos.
Cómo mostrar una variable específica en el flujo
El objetivo principal es hacer más visual y sencillo entender cómo navegar por el JSON devuelto por la API y cómo utilizar sus valores dentro de los mensajes del chatbot. A continuación, se presentan ejemplos más claros y prácticos que pueden reemplazar o complementar la sección actual de la documentación.
Cómo acceder a una variable específica de la API
Toda respuesta de la API queda disponible en la variable predeterminada:
<? $resposta_api.body ?>
Contiene todo el JSON devuelto por la llamada a la API.
Ejemplo 1 — Mostrar solo el nombre del cliente
Respuesta de la API
Para acceder únicamente al nombre del cliente, utilice:
<? $resposta_api.body.cliente.nome ?>
Mensaje en el bloque del flujo
Resultado mostrado al usuario:
¡Hola, Carlos Silva!
Utilice este patrón cuando desee mostrar solo un campo específico de la respuesta de la API.
Ejemplo 2 — Mostrar más de una información del cliente
Respuesta de la API, mensaje en el bloque del flujo y resultado mostrado:
¡Hola, Carlos Silva!
Su plan actual es Premium. Correo electrónico registrado: carlos@email.com.
Aquí el usuario comprende que cada campo del JSON puede ser accedido por separado.
Ejemplo 3 — Mostrar un valor dentro de un arreglo
Respuesta de la API
Para acceder al primer pedido, utilice el índice [0]:
<? $resposta_api.body.pedidos[0].numero ?>
Para acceder al estado del primer pedido:
<? $resposta_api.body.pedidos[0].status ?>
Mensaje en el bloque del flujo
Resultado mostrado
Su pedido 12345 está con estado "En tránsito".
Utilice [0] para el primer elemento del arreglo, [1] para el segundo, y así sucesivamente.
Ejemplo 4 — Comprender la ruta de la variable
Respuesta de la API
La ruta hasta la ciudad es:
Cliente → Dirección → Ciudad
Por lo tanto, la variable correcta será:
<? $resposta_api.body.cliente.endereco.cidade ?>
Mensaje en el flujo
Resultado:
Ciudad del cliente: São Paulo
La regla es simple: siga la estructura del JSON utilizando punto (.) para objetos y [n] para listas.
Ejemplo visual del flujo correcto
Flujo recomendado
⚠️ Importante: Los datos devueltos por la API solo estarán disponibles después de que finalice la ejecución del bloque de API. Por ello, la visualización debe realizarse en un bloque posterior.