Send Contact

Sends one or more contact cards (vCard) via WhatsApp. This is supported on WhatsApp, Z-API, and ZapperHUB channels.

Authentication: Requires a valid API key or session. Pass as Authorization: Bearer <api_key>.

​

Request Body

The API uses a dynamic schema to reconstruct a contact object from flat parameters.

​

Required Parameters

• agentId: The ID of the agent sending the message.
• conversationId: The ID of the conversation to send to.
• name_formatted_name: Full name as it should appear in the contact card.
• name_first_name: First name. Required by Meta’s API even though documented as optional.
• phone_1_phone: Phone number.

​

Optional Parameters

Name fields

• name_last_name: Last name.
• name_middle_name: Middle name.
• name_suffix: Name suffix (e.g., “Jr.”, “Esq.”).
• name_prefix: Name prefix (e.g., “Dr.”, “Ms.”).

Phone fields (up to multiple phones)

• phone_1_type: Type of phone (e.g., CELL, WORK, HOME, Mobile, Landline).
• phone_1_wa_id: WhatsApp ID for the phone. When this matches the recipient, WhatsApp shows Message and Save to Contacts buttons.
• phone_2_phone, phone_2_type, phone_2_wa_id: Second phone number.

Email fields (up to multiple emails)

• email_1_email: Email address.
• email_1_type: Type of email (e.g., WORK, HOME).
• email_2_email, email_2_type: Second email.

Address fields (up to multiple addresses)

• address_1_street: Street address.
• address_1_city: City.
• address_1_state: State code.
• address_1_zip: ZIP / postal code.
• address_1_country: Country name.
• address_1_country_code: 2-letter country code (e.g., BR, US).
• address_1_type: Address type (e.g., HOME, WORK).

Organization fields

• org_company: Company name.
• org_department: Department.
• org_title: Job title.

URL fields

• url_1_url: Website URL.
• url_1_type: URL type (e.g., WORK, COMPANY).

Other

• birthday: Date of birth (YYYY-MM-DD format).

​

Important Notes

• name_first_name is required by Meta — the API auto-fills it from name_formatted_name if omitted.
• If phone_1_wa_id matches the recipient, WhatsApp shows Message + Save buttons. Without it, only generic contact info is shown.
• The message is only saved to the conversation history if Meta confirms delivery with a message ID.

​

Example (minimal)

{
  "agentId": "agent-123",
  "conversationId": "conv-456",
  "name_formatted_name": "John Doe",
  "name_first_name": "John",
  "phone_1_phone": "+5512996130832",
  "phone_1_wa_id": "5512996130832"
}

​

Example (full)

{
  "agentId": "agent-123",
  "conversationId": "conv-456",
  "name_formatted_name": "John Doe",
  "name_first_name": "John",
  "name_last_name": "Doe",
  "phone_1_phone": "+5512996130832",
  "phone_1_type": "Mobile",
  "phone_1_wa_id": "5512996130832",
  "phone_2_phone": "+5511999998888",
  "phone_2_type": "Work",
  "email_1_email": "john@example.com",
  "email_1_type": "Work",
  "address_1_street": "Rua Augusta, 1500",
  "address_1_city": "São Paulo",
  "address_1_state": "SP",
  "address_1_zip": "01304-001",
  "address_1_country": "Brazil",
  "address_1_country_code": "BR",
  "address_1_type": "Work",
  "org_company": "Chatvolt",
  "org_department": "Engineering",
  "org_title": "Developer",
  "url_1_url": "https://chatvolt.ai",
  "url_1_type": "Company",
  "birthday": "1990-05-15"
}

​

Error Responses

The endpoint returns errors in the following scenarios:

On success, returns the Meta API response including the message ID.

{
  "success": true,
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+5512996130832", "wa_id": "5512996130832" }],
  "messages": [{ "id": "wamid.HBgNNTUxMjk5NjEzMDgzMhUCABEYEkRBOEVEMTg2ODBDQTFGNTdDNwA=" }]
}