Saltar al contenido principal
POST
/
api
/
message
/
contact
/
:instance
Enviar contacto
curl --request POST \
  --url https://api.example.com/api/message/contact/:instance \
  --header 'Content-Type: <content-type>' \
  --header 'token: <token>' \
  --data '
{
  "number": "<string>",
  "vcard": [
    {}
  ],
  "vcard[].fullName": "<string>",
  "vcard[].phone": "<string>",
  "vcard[].organization": "<string>",
  "vcard[].email": "<string>",
  "vcard[].url": "<string>",
  "delay": 123,
  "replyTo": "<string>",
  "replyPrivate": true,
  "source": "<string>"
}
'
Auth: TokenAccount o TokenInstance • Rate-limit: Global (100/min) • Idempotente: no

​
Descripción

Envía uno o más contactos como vCard. El destinatario recibe una tarjeta clicable que puede agregar el contacto directamente a su libreta de direcciones. El campo vcard acepta un array de objetos VCard (envío múltiple) o un único objeto (compatibilidad hacia atrás, el servidor acepta ambos formatos). Soporta replyTo, replyPrivate, delay (en segundos) y source. No soporta menciones.

​
Ejemplos

​
Contacto único

Envía un vCard con lo mínimo (fullName y phone). El destinatario recibe una única tarjeta clicable con el contacto “João Silva” listo para ser agregado a su libreta de direcciones. 
curl -X POST "https://ryzeapi.cloud/api/message/contact/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "vcard": [
      {
        "fullName": "João Silva",
        "phone":    "5511888888888"
      }
    ]
  }'

​
Múltiples contactos

Pasa tres contactos en el array vcard. El servidor envía todo como un único ContactsArrayMessage; el destinatario ve una tarjeta agrupada y elige qué nombres agregar a su libreta de direcciones. 
curl -X POST "https://ryzeapi.cloud/api/message/contact/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "vcard": [
      {
        "fullName": "João Silva",
        "phone":    "5511888888888"
      },
      {
        "fullName": "Maria Souza",
        "phone":    "5511777777777"
      },
      {
        "fullName": "Carlos Lima",
        "phone":    "5511666666666"
      }
    ]
  }'

​
Contacto con organización, email y sitio web

Incluye los campos opcionales organization, email y url en el vCard. La tarjeta resultante muestra la empresa, el email de contacto y el sitio web debajo del nombre, ideal para presentar contactos comerciales completos. 
curl -X POST "https://ryzeapi.cloud/api/message/contact/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511999999999",
    "vcard": [
      {
        "fullName":     "João Silva",
        "phone":        "5511888888888",
        "organization": "Example S.A.",
        "email":        "joao@example.com",
        "url":          "https://example.com"
      }
    ]
  }'

​
Respuesta exitosa

El array vcard en la respuesta refleja exactamente lo que enviaste (con todos los contactos). Cuando hay más de un contacto, message se vuelve "X contacts sent successfully in one message".
200 OK
{
  "success": true,
  "message": "Contact sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "contact",
    "vcard": [
      {
        "fullName":     "João Silva",
        "phone":        "5511888888888",
        "organization": "Example S.A.",
        "email":        "joao@example.com",
        "url":          "https://example.com"
      }
    ],
    "source":    "api",
    "timestamp": "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}
Cuando vcard contiene un solo elemento, el servidor lo envía como ContactMessage. Para múltiples elementos, se envía como ContactsArrayMessage (un único mensaje agrupando varias tarjetas).

​
Parámetros de ruta

​
instance
string
requerido
Nombre de la instancia (p. ej., $Instance_Name).

​
Cabeceras

​
token
string
requerido
TokenAccount o TokenInstance.
​
Content-Type
string
requerido
application/json

​
Cuerpo de la solicitud

​
number
string
requerido
Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
vcard
VCard[]
requerido
Array de contactos a enviar. Cada elemento sigue la estructura abajo. El handler también acepta un único objeto VCard (sin array) por compatibilidad hacia atrás, convirtiéndolo internamente a un array de un solo elemento. Se requiere al menos un contacto.
​
vcard[].fullName
string
requerido
Nombre completo del contacto. Aparece como la etiqueta principal de la tarjeta.
​
vcard[].phone
string
requerido
Número de teléfono del contacto (con código de país, p. ej., 5511888888888).
​
vcard[].organization
string
Organización/empresa del contacto (opcional).
​
vcard[].email
string
Email del contacto (opcional).
​
vcard[].url
string
URL/sitio web del contacto (opcional).
​
delay
int
predeterminado:"0"
Tiempo en segundos a esperar antes de enviar. Durante el intervalo, el servidor envía el indicador “escribiendo…” al destinatario y dispara “pausado” antes del envío real.
​
replyTo
string
ID del mensaje a citar (respuesta). El mensaje original debe pertenecer a la misma instancia y haber sido guardado en la base de datos.
​
replyPrivate
boolean
predeterminado:"false"
Cuando es true y replyTo apunta a un mensaje originado en un grupo, la respuesta se redirige al chat privado del autor original (manteniendo la cita). Ignorado si el mensaje original no es de un grupo. Aviso: este campo está definido en la struct pero el handler de contactos hace parsing manual del JSON y no está extrayendo replyPrivate del payload, por lo que actualmente se trata como false.
​
source
string
predeterminado:"api"
Identificador de origen para trazabilidad (p. ej., crm, bot-suporte, n8n). Guardado en el registro del mensaje en la base de datos y propagado a los webhooks. Cuando se omite, el default es "api".

​
Notas

  • delay es en segundos, no milisegundos.
  • El campo vcard acepta tanto un array como un objeto único. Recomendamos usar siempre un array ([ {...} ]) para evitar ambigüedad.
  • Cada contacto requiere fullName y phone. organization, email y url son opcionales.
  • Para envíos múltiples, WhatsApp agrupa los contactos en una única tarjeta en el chat, el destinatario puede elegir cuáles agregar.
  • Los mensajes de contacto no soportan mention ni mentionAll.
  • Para números BR (que comienzan con 55), el servicio prueba automáticamente variaciones con y sin el 9° dígito.
  • Cada contacto en el array pasa por validación individual; si el elemento N falla, la respuesta es 400 Contact full name is required for contact N o 400 Contact phone number is required for contact N.

​
Errores

HTTPStatus internoMensaje
400,Instance name is required
400,Invalid JSON format: <detail>
400,Failed to read request body: <detail>
400,Number is required
400,At least one contact (vcard) is required
400,Contact full name is required for contact N
400,Contact phone number is required for contact N
400invalid_numberInvalid phone number format: <detail>
500send_failedFailed to send message: <reason>
404,Instance not found
503disconnectedInstance is not connected to WhatsApp
Envoltorio de error: 
{
  "success": false,
  "error": { "message": "At least one contact (vcard) is required" }
}