Enviar contacto

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"
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/contact/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    vcard: [
      {
        fullName: "João Silva",
        phone:    "5511888888888"
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/contact/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "vcard": [
            {
                "fullName": "João Silva",
                "phone":    "5511888888888"
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "vcard": [
            {
                "fullName": "João Silva",
                "phone":    "5511888888888"
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/contact/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/contact/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    vcard: [
      { fullName: "João Silva",   phone: "5511888888888" },
      { fullName: "Maria Souza",  phone: "5511777777777" },
      { fullName: "Carlos Lima",  phone: "5511666666666" }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/contact/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "vcard": [
            {"fullName": "João Silva",  "phone": "5511888888888"},
            {"fullName": "Maria Souza", "phone": "5511777777777"},
            {"fullName": "Carlos Lima", "phone": "5511666666666"}
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "vcard": [
            { "fullName": "João Silva",  "phone": "5511888888888" },
            { "fullName": "Maria Souza", "phone": "5511777777777" },
            { "fullName": "Carlos Lima", "phone": "5511666666666" }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/contact/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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"
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/contact/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number: "5511999999999",
    vcard: [
      {
        fullName:     "João Silva",
        phone:        "5511888888888",
        organization: "Example S.A.",
        email:        "joao@example.com",
        url:          "https://example.com"
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/contact/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number": "5511999999999",
        "vcard": [
            {
                "fullName":     "João Silva",
                "phone":        "5511888888888",
                "organization": "Example S.A.",
                "email":        "joao@example.com",
                "url":          "https://example.com"
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number": "5511999999999",
        "vcard": [
            {
                "fullName":     "João Silva",
                "phone":        "5511888888888",
                "organization": "Example S.A.",
                "email":        "joao@example.com",
                "url":          "https://example.com"
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/contact/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

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

string

requerido

Nombre de la instancia (p. ej., $Instance_Name).

Cabeceras

string

requerido

TokenAccount o TokenInstance.

string

requerido

application/json

Cuerpo de la solicitud

string

requerido

Destino: teléfono (5511999999999) o JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

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.

string

requerido

Nombre completo del contacto. Aparece como la etiqueta principal de la tarjeta.

string

requerido

Número de teléfono del contacto (con código de país, p. ej., 5511888888888).

string

Organización/empresa del contacto (opcional).

string

Email del contacto (opcional).

string

URL/sitio web del contacto (opcional).

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.

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.

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.

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

HTTP	Status interno	Mensaje
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`
400	`invalid_number`	`Invalid phone number format: <detail>`
500	`send_failed`	`Failed to send message: <reason>`
404	,	`Instance not found`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envoltorio de error:

{
  "success": false,
  "error": { "message": "At least one contact (vcard) is required" }
}

Introducción

Instancia

Eventos

Mensajes

Llamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidad

Enviar contacto

Descripción

Ejemplos

Contacto único

Múltiples contactos

Contacto con organización, email y sitio web

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores

​Descripción

​Ejemplos

​Contacto único

​Múltiples contactos

​Contacto con organización, email y sitio web

​Respuesta exitosa

​Parámetros de ruta

​Cabeceras

​Cuerpo de la solicitud

​Notas

​Errores

Descripción

Ejemplos

Contacto único

Múltiples contactos

Contacto con organización, email y sitio web

Respuesta exitosa

Parámetros de ruta

Cabeceras

Cuerpo de la solicitud

Notas

Errores