Skip to main content
POST
/
api
/
message
/
contact
/
:instance
Send Contact
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 or TokenInstance • Rate-limit: Global (100/min) • Idempotent: no

​
Description

Sends one or more contacts as vCard. The recipient gets a clickable card that can add the contact directly to their address book. The vcard field accepts an array of VCard objects (multi-send) or a single object (backward compatibility, the server accepts both formats). Supports replyTo, replyPrivate, delay (in seconds) and source. Does not support mentions.

​
Examples

​
Single contact

Sends a vCard with the bare minimum (fullName and phone). The recipient gets a single clickable card with the contact “João Silva” ready to be added to their address book. 
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"
      }
    ]
  }'

​
Multiple contacts

Passes three contacts in the vcard array. The server sends everything as a single ContactsArrayMessage; the recipient sees a grouped card and chooses which names to add to their address book. 
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"
      }
    ]
  }'

​
Contact with organization, email and website

Includes the optional fields organization, email and url in the vCard. The resulting card displays the company, the contact email and the website below the name, ideal for presenting full business contacts. 
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"
      }
    ]
  }'

​
Success response

The vcard array in the response echoes exactly what you sent (with all contacts). When there is more than one contact, message becomes "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"
    }
  }
}
When vcard contains a single item, the server sends it as ContactMessage. For multiple items, it is sent as ContactsArrayMessage (a single message grouping multiple cards).

​
Path parameters

​
instance
string
required
Instance name (e.g., $Instance_Name).

​
Headers

​
token
string
required
TokenAccount or TokenInstance.
​
Content-Type
string
required
application/json

​
Request body

​
number
string
required
Destination: phone (5511999999999) or JID (@s.whatsapp.net, @lid, @g.us, @newsletter).
​
vcard
VCard[]
required
Array of contacts to send. Each item follows the structure below. The handler also accepts a single VCard object (without an array) for backward compatibility, internally converting it to a single-item array. At least one contact is required.
​
vcard[].fullName
string
required
Full name of the contact. Appears as the main label of the card.
​
vcard[].phone
string
required
Phone number of the contact (with country code, e.g., 5511888888888).
​
vcard[].organization
string
Contact organization/company (optional).
​
vcard[].email
string
Contact email (optional).
​
vcard[].url
string
Contact URL/website (optional).
​
delay
int
default:"0"
Time in seconds to wait before sending. During the interval, the server sends the “typing…” indicator to the recipient and fires “paused” before the actual send.
​
replyTo
string
ID of the message to be quoted (reply). The original message must belong to the same instance and have been saved in the database.
​
replyPrivate
boolean
default:"false"
When true and replyTo points to a message originating from a group, the reply is redirected to the original author’s private chat (keeping the quote). Ignored if the original message is not from a group. Advisory: this field is defined in the struct but the contacts handler does manual JSON parsing and is not extracting replyPrivate from the payload, so it is currently treated as false.
​
source
string
default:"api"
Origin identifier for traceability (e.g., crm, bot-suporte, n8n). Saved on the message record in the database and propagated to webhooks. When omitted, defaults to "api".

​
Notes

  • delay is in seconds, not milliseconds.
  • The vcard field accepts both an array and a single object. We recommend always using an array ([ {...} ]) to avoid ambiguity.
  • Each contact requires fullName and phone. organization, email and url are optional.
  • For multi-sends, WhatsApp groups the contacts into a single card in the chat, the recipient can choose which to add.
  • Contact messages do not support mention or mentionAll.
  • For BR numbers (starting with 55), the service automatically tries variations with and without the 9th digit.
  • Each contact in the array goes through individual validation; if item N fails, the response is 400 Contact full name is required for contact N or 400 Contact phone number is required for contact N.

​
Errors

HTTPInternal statusMessage
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
Error envelope: 
{
  "success": false,
  "error": { "message": "At least one contact (vcard) is required" }
}