← All posts
Tutorial

WhatsApp Contact API: Add a Contact vs Send a vCard

Adding a WhatsApp contact and sending a contact card are two different API jobs. Use POST /v1/accounts/{account_id}/contacts/add when you want to change the connected account’s contact list. Use POST /v1/messages with message.type: "contact" when you want to deliver one or more structured contact cards in a chat. Sending a card is not a substitute for the address-book operation.

Key takeaways

  • Add contact changes the connected channel account’s contact list.
  • Send contact delivers contact details as a message to a user or group.
  • The add operation accepts at least one of phone_number or username.
  • The send operation requires a non-empty message.contacts array, and every card needs name.
  • Both operations currently target WhatsApp in UnifyPort, but they use different routes and return different unsupported-operation errors.

WhatsApp add contact vs send vCard

GoalRouteRequired inputResult
Save a person to the connected account’s contact listPOST /v1/accounts/{account_id}/contacts/addphone_number or usernameA contact object with identifiers such as id and conversation_id
Share contact details inside a chatPOST /v1/messagesaccount_id, to, and a contact message containing at least one named cardAn accepted message result with message_id

The distinction matters because the first route manages account state, while the second sends content. A support workflow might add a customer so the account can recognize that person later. A handoff workflow might instead send a sales representative’s card to the customer. Some workflows legitimately do both, but they should remain two explicit calls.

If you are still choosing the broader WhatsApp integration path, compare the Cloud API, BSP, and unofficial interface options before implementing contact operations. For the history of the structured contact message in UnifyPort, see the API update that introduced contact/vCard messages.

Option 1: add a contact to the connected account

The Add contact API reference documents this request:

curl -X POST https://api.unifyport.ai/v1/accounts/acc_8c21d0/contacts/add \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "8600000000000",
    "whatsapp_options": {
      "first_name": "Jane",
      "full_name": "Jane Doe",
      "sync_to_device_contacts": false
    }
  }'

Provide at least one of phone_number or username. WhatsApp-specific naming and device-sync controls belong under whatsapp_options; do not move first_name, full_name, or sync_to_device_contacts to the top level.

A successful response returns the contact representation. Keep the returned conversation_id when you need the chat identifier for later messaging or contact-list operations. Do not derive that identifier from the phone number: use the API response.

Choose this operation when your requirement is phrased as “save this person,” “make this contact part of the connected account’s address book,” or “obtain the canonical contact and conversation identifiers after adding them.” Providers that do not implement this action return 501 unsupported_by_provider.

Option 2: send one or more vCard contact messages

The Send contact message reference uses the unified message route:

curl -X POST https://api.unifyport.ai/v1/messages \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_8c21d0",
    "to": {
      "id": "8613912345678@s.whatsapp.net",
      "type": "user"
    },
    "message": {
      "type": "contact",
      "contacts": [
        {
          "name": "Jane Doe",
          "phones": [{ "number": "+8613800000000", "type": "CELL" }],
          "emails": [{ "address": "jane@example.com" }],
          "organization": "ACME",
          "title": "PM"
        }
      ]
    }
  }'

UnifyPort generates the vCard from structured JSON. You do not need to assemble raw BEGIN:VCARD text. The vCard format itself is standardized in RFC 6350, while the fields accepted by this API are the narrower documented set shown above.

Each card requires name. phones[].number, emails[].address, organization, and title are optional. The array can contain one or multiple cards. An empty array, or a card without name, returns 400 invalid_request. A non-WhatsApp account returns 400 unsupported_message_type for this message type.

Choose this operation when the requirement says “share the account manager’s details,” “send a supplier’s card,” or “deliver several escalation contacts in the conversation.” Check the provider message support matrix before treating contact cards as a cross-platform message type.

A safe two-step workflow when you need both

  1. Add the customer with /contacts/add only if the connected account’s contact list must change.
  2. Store the returned identifiers, especially conversation_id, in your own workflow record.
  3. Send the representative’s card with /v1/messages as a separate action.
  4. Record both API results separately. A successful contact addition does not prove that the card message was accepted, and an accepted card message does not prove that an address-book update happened.
  5. Branch on machine-readable errors. Handle unsupported_by_provider, unsupported_message_type, and invalid_request according to the operation that produced them.

This separation also makes retries clearer. If message delivery needs to be retried, you should not automatically repeat an already successful address-book mutation.

Limitations and trade-offs

These contact operations currently have WhatsApp-specific support in UnifyPort. If your product needs one identical contact-card send across Telegram, LINE, TikTok, Zalo, and X, use the provider capability matrix and design a text fallback rather than assuming the structured type exists everywhere.

The API produces a valid structured card, but the recipient’s app and user still control how that card is viewed or saved. Also keep personal data collection proportionate to the workflow: send only the phone, email, organization, and title fields that the recipient actually needs.

FAQ

Does sending a WhatsApp vCard add the person to my connected account’s contacts?

No. UnifyPort exposes that as a separate operation. Use /contacts/add for the contact list and /v1/messages with message.type: "contact" for the chat message.

Can I send multiple contact cards in one request?

Yes. Put multiple card objects in message.contacts. Every object must include name.

Is phone_number required when adding a contact?

Not always. The add-contact request requires at least one of phone_number or username.

Can I send this contact message through LINE or Telegram?

Not with the documented structured contact send operation. It currently supports WhatsApp; other providers return 400 unsupported_message_type.

Should I generate the vCard string myself?

No. Send the documented structured JSON and let UnifyPort generate the vCard.

Next step

Start with the send contact message API reference if your goal is to share details in a chat. If your real goal is address-book management, use the add contact reference instead.

Sources

Sources and provider support were checked on August 14, 2026.