Ir al contenido

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" }
  }'
CampoQué es
location.latitudeLatitud, de -90 a 90.
location.longitudeLongitud, de -180 a 180.
location.nameOpcional. El nombre del lugar (hasta 200 caracteres), en negritas en WhatsApp.
location.addressOpcional. 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: true cuando 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 (solo http o https).
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 en vcard.
  • vcard: la tarjeta tal como llegó, para que tu sistema tome lo que necesite (correo, empresa…). Es null si 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).