Apariencia
Ubicaciones y contactos
Se envían con el mismo endpoint que el texto, POST /api/v1/messages, en JSON. Necesitas el scope messages:send y una instancia conectada. Como cualquier mensaje, la respuesta es 202 Accepted con status: "queued", cuenta como un mensaje y acepta reply_to e Idempotency-Key.
Enviar una ubicación
bash
curl -X POST "https://zappio.cloud/api/v1/messages" \
-H "Authorization: Bearer $ZAPPIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instance": "ins_...",
"to": "5215500000000",
"type": "location",
"location": { "latitude": 19.4326, "longitude": -99.1332, "name": "Sucursal Centro", "address": "Av. Juárez 10, CDMX" }
}'| Campo | Qué es |
|---|---|
location.latitude | Latitud, de -90 a 90. |
location.longitude | Longitud, de -180 a 180. |
location.name | Opcional. El nombre del lugar (hasta 200 caracteres), en negritas en WhatsApp. |
location.address | Opcional. La dirección (hasta 300 caracteres). |
Enviar contactos
bash
curl -X POST "https://zappio.cloud/api/v1/messages" \
-H "Authorization: Bearer $ZAPPIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"instance": "ins_...",
"to": "5215500000000",
"type": "contact",
"contacts": [{ "name": "Soporte ZAPPIO", "phones": ["+52 55 0000 0001"] }]
}'contacts lleva de 1 a 10 contactos; cada uno con su name (hasta 120 caracteres) y de 1 a 5 phones en formato internacional. ZAPPIO arma la tarjeta (vCard) de cada uno; en WhatsApp aparecen los botones "Enviar mensaje" y "Agregar".
Cómo llegan
Un mensaje de ubicación trae location; uno de contactos trae contacts. Los dos llegan igual por la API (GET /messages) y en los webhooks message.received (lo que te escriben) y message.sent_external (lo que se envió desde el teléfono):
json
{
"type": "location",
"text": null,
"location": {
"latitude": 19.4326,
"longitude": -99.1332,
"name": "Sucursal Centro",
"address": "Av. Juárez 10, CDMX",
"url": null,
"live": false
},
"contacts": null
}location.live:truecuando el contacto compartió su ubicación en tiempo real. ZAPPIO guarda el punto desde donde la compartió; no sigue sus movimientos.location.url: el enlace que el remitente agregó al lugar, si hay (solohttpohttps).
json
{
"type": "contact",
"location": null,
"contacts": [
{
"name": "Ana López",
"phones": ["5255000000001"],
"vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Ana López\nTEL;type=CELL;waid=5255000000001:+52 55 0000 0001\nEND:VCARD"
}
]
}phones: los teléfonos de la tarjeta que no dejan duda: los que WhatsApp identifica y los escritos con código de país. Un número guardado sin código de país solo queda envcard.vcard: la tarjeta tal como llegó, para que tu sistema tome lo que necesite (correo, empresa…). Esnullsi no venía o si pasaba de 16 KB (una tarjeta con foto).
Los stickers llegan como type: "sticker" con su archivo WebP en media, igual que una imagen (Multimedia).
Mensajes unsupported
Lo que WhatsApp entrega y ZAPPIO no puede leer (un pago, un producto o catálogo, botones, un evento, una invitación a grupo…) llega como type: "unsupported", sin contenido: text, media, location y contacts en null. Así no se pierde: sabes que el contacto escribió y cuándo, y puedes abrir el chat en WhatsApp para verlo. Un mensaje unsupported no se puede enviar ni reenviar (422 UNSUPPORTED_MESSAGE_TYPE).