Skip to content

A glossary story9 chapters · 5 min read

Contacts Message

A WhatsApp message carrying one or more contact cards, with names, phone numbers, emails and addresses, that the recipient can save in one tap.

Also called: Contact card message · WhatsApp contact card · vCard message · Contacts message type

Reviewed

Follow along

Open the card and see what each field does

9 / 9
{
  "messaging_product": "whatsapp",
  "to": "919812345678",
  "type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "Cardiology OPD (Patna)",
        "first_name": "Cardiology",
        "last_name": "OPD"
      },
      "org": {
        "company": "Demo Heart Clinic",
        "department": "Cardiology",
        "title": "Appointments desk"
      },
      "phones": [
        {
          "phone": "+91 612 255 0100",
          "type": "WORK"
        },
        {
          "phone": "+91 98765 43210",
          "type": "WORK",
          "wa_id": "919876543210"
        }
      ],
      "emails": [
        {
          "email": "opd@example.in",
          "type": "WORK"
        }
      ],
      "addresses": [
        {
          "street": "Exhibition Road",
          "city": "Patna",
          "state": "BR",
          "zip": "800001",
          "country": "India",
          "country_code": "IN",
          "type": "WORK"
        }
      ],
      "urls": [
        {
          "url": "https://clinic.example.in/cardiology",
          "type": "WORK"
        }
      ]
    }
  ]
}
The payload the clinic sends to share its cardiology desk as a contact card. Step through the fields that decide what the patient sees and which buttons the card offers.

Field 9: contacts.0.urls.0.url — A website or booking page saved with the contact.

Chapter 1 · The scenario

Example: Handing a patient the right desk in Patna

A Patna heart clinic's front-desk bot is asked how to reach the cardiology OPD. Instead of typing a number, it sends a contacts message: "Cardiology OPD (Patna)" with the department's landline, its WhatsApp-enabled appointment number carrying a wa_id, the OPD email and the clinic's address. The patient taps Save contact and has the right number for next time. Later she shares her father's card so the clinic can send him his report; the bot stores the number as a pending contact and sends nothing to it until her father messages the clinic himself.

— Handing a patient the right desk in Patna

Chapter 2 · What is a contacts message?

A contacts message is the WhatsApp message type (type: "contacts") for sharing contact cards. Instead of typing a phone number into a text, the business sends a structured card — a name, one or more phone numbers, emails, postal addresses, an organisation and job title, websites, a birthday — and the recipient sees a bubble they can open to save the contact, call it or start a chat. Customers can share cards the same way, for example to refer a friend or nominate a family member.

On the Cloud API the payload is a contacts array of card objects. The only required field on a card is name.formatted_name, the name shown in the bubble; first_name, last_name, middle_name, prefix and suffix sit beside it. phones, emails, addresses and urls are arrays, so one card can carry a support line and a sales line; org holds company, department and title; birthday uses YYYY-MM-DD; addresses take a two-letter country_code. A single message can carry up to 257 cards, although Meta recommends far fewer.

One field changes the experience: wa_id inside a phone entry. With it, the card shows Message and Save contact buttons, and Message opens a chat with that number; without it, WhatsApp shows an Invite to WhatsApp button instead. Inbound cards arrive in the messages webhook as type: "contacts" with the same structure — not to be confused with the webhook contacts object, the contacts array at the top of every inbound webhook that describes who sent the message. Like other free-form types, a contacts message can be sent only inside an open customer service window.

Key takeaways

  • A contacts message sends one or more contact cards that the recipient can save, call or message in one tap.
  • Each card needs only name.formatted_name; phones, emails, addresses, organisation, URLs and birthday are optional.
  • Add wa_id to a phone entry to show Message and Save contact buttons; without it WhatsApp shows Invite to WhatsApp.
  • Shared cards arrive as type: contacts inside messages[], unlike the top-level contacts array that describes the sender.
  • One message can carry up to 257 cards, but Meta recommends sending fewer.

Chapter 3 · In code

A contacts message in code

curl -X POST "https://graph.facebook.com/v26.0/{PHONE_NUMBER_ID}/messages" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "to": "919812345678",
    "type": "contacts",
    "contacts": [{
      "name": { "formatted_name": "Cardiology OPD (Patna)", "first_name": "Cardiology", "last_name": "OPD" },
      "org": { "company": "Demo Heart Clinic", "department": "Cardiology" },
      "phones": [
        { "phone": "+91 612 255 0100", "type": "WORK" },
        { "phone": "+91 98765 43210", "type": "WORK", "wa_id": "919876543210" }
      ],
      "emails": [{ "email": "opd@example.in", "type": "WORK" }]
    }]
  }'

The second phone has a wa_id, so the card shows Message and Save contact buttons.

Chapter 4 · How it unfolds

How does a contacts message work?

  1. Build the card

    Create a contacts array with one object per person or desk, and set name.formatted_name exactly as it should appear in the customer's address book.

  2. Add reachable details

    Fill phones in international format with a type such as WORK, and add wa_id to any number that is on WhatsApp so the card offers a Message button. Add emails, urls and an address only if they help.

  3. Send inside the window

    POST to /{PHONE_NUMBER_ID}/messages with type: "contacts". It is a session message, so the customer must have messaged you in the last 24 hours.

  4. Receive shared cards

    When a customer shares a contact, messages[0].type is contacts and the card sits in messages[0].contacts. Normalise the numbers to E.164 before storing or matching them.

  5. Ask before you use them

    A shared card is a third person's data. Store it, but message that person only once they have opted in themselves.

Chapter 5 · The facts

A contacts message: key facts and limits

Message typecontacts
Required per cardname.formatted_name
Optional fieldsphones, emails, addresses, org, urls, birthday
Birthday formatYYYY-MM-DD
Cards per messageUp to 257 (fewer recommended)
Phone with wa_idMessage and Save contact buttons
Phone without wa_idInvite to WhatsApp button
When you can sendInside an open customer service window

Chapter 6 · Where it goes wrong

Common mistakes with a contacts message

  • Leaving out wa_id

    Without it the card offers Invite to WhatsApp instead of Message, even for your own WhatsApp support line. Add the number's wa_id — digits only, country code first.

  • Reading the wrong contacts array

    value.contacts in every inbound webhook is the sender's profile; messages[].contacts exists only when the message is a shared card. Parsers that mix them save the sender as the shared contact.

  • Messaging people from shared cards

    A card a customer forwards is not that person's consent. Keep it, but contact them only after they opt in directly.

  • Storing numbers as typed

    Phone fields arrive with spaces, dashes and local prefixes. Normalise to E.164 before matching against your CRM, or the same person ends up as three contacts.

Chapter 7 · Why it matters

Why does a contacts message matter?

Numbers typed into a chat get mistyped, lost in the scroll and never saved, so the next time a customer needs help they search the web and find a fake "customer care" listing. A contacts message hands them the real line in a form their phone understands — saved in one tap, under the right name — and lets a business introduce a specific person, such as a relationship manager or a branch desk, without anyone copying details by hand.

Chapter 8 · What good teams do

Best practices for a contacts message

  • Name the card the way customers search for you: "Acme Support (Pune)" beats a legal entity name.
  • Send a card at the end of a resolved conversation so the right number is saved for next time.
  • Use org.title for a named relationship manager so the saved contact says who they are.
  • Keep each card to the numbers a customer actually needs; a card listing six lines is hard to use.

Chapter 9 · Contacts Message FAQs

Contacts Message FAQs

How do I send a contact card through the WhatsApp API?+
Send a message with type contacts and a contacts array. Each card needs name.formatted_name; add phones (with wa_id for WhatsApp numbers), emails, addresses, org and urls as needed, inside an open customer service window.
Why does my contact card show Invite to WhatsApp instead of Message?+
Because the phone entry has no wa_id. Add the WhatsApp ID of that number to the phone object and the card shows Message and Save contact buttons instead.
How many contacts can one WhatsApp contacts message carry?+
Up to 257 cards, though Meta recommends sending fewer. In practice one to three cards per message keeps the bubble readable.
What is the difference between a contacts message and the webhook contacts object?+
A contacts message is a card someone chose to share; the webhook contacts object describes the sender. The first sits inside messages[] when its type is contacts; the second is the contacts array at value level in every inbound webhook.
Can I send a contacts message outside the 24-hour window?+
No. It is a free-form message, so it needs an open customer service window. Outside it, send an approved template first and share the card once the customer replies.

See InfiQ pricing

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms