Guides

Contacts Message

Suggest Edits

Contacts message allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses.

When a WhatsApp user taps the message's profile arrow, it displays the contact's information in a profile view:

HTTP Request : POST / notification

The Contacts message example includes the following contact information:



{
  "channel": "WHATSAPP",
  "request": {
      "message": "message text body of the registered template",
      "from": "1000000001",
      "to": "+1000000002",
      "type": "contacts",
      "contacts": [
          {
              "addresses": [
                  {
                      "city": "Menlo Park",
                      "country": "United States",
                      "country_code": "us",
                      "state": "CA",
                      "street": "1 Hacker Way",
                      "type": "HOME",
                      "zip": "94025"
                  }
              ],
              "birthday": "2012-08-18",
              "emails": [
                  {
                      "email": "[email protected]",
                      "type": "WORK"
                  }
              ],
              "name": {
                  "first_name": "Joe",
                  "formatted_name": "Dr. Joe Doe Smith",
                  "last_name": "Smith"
              },
              "org": {
                  "company": "EliPackage",
                  "department": "Programming",
                  "title": "Lead Programmer"
              },
              "phones": [
                  {
                      "phone": "+525544444444",
                      "type": "HOME"
                  },
                  {
                      "phone": "+525555555555",
                      "type": "MOBILE",
                      "wa_id": "16505551234"
                  }
              ],
              "urls": [
                  {
                      "url": "https://www.facebook.com",
                      "type": "WORK"
                  }
              ]
          }
      ]
   }
}

The parameters presented in the request body example when creating the Session Contacts message are the following:

Parameter Required Description
channel Yes

Specifies the type of delivery channel which the notification message will be sent: "SMS", "EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "WHATSAPP" value to send the WhatsApp message.
request Yes Message content.
request.message Yes

request.from Yes

Phone number of the sender.

Phone number provided during the WABA account setup will be used as the sender of the notification message.

Only accepts numeric characters. Do not include the "+" sign.
request.to Yes Determines the destination phone number for your session message. Numbers are specified in E.164 format → (‘+’ and a country code).
request.type Yes

Type of message you want to send.

Supported options:

  • "text": Sends a plain text message.

  • "image": Sends an image file (.jpeg, .png).

  • "audio": Sends an audio file (.acc, .mp3, .amr, .mpeg).

  • "video": Sends a video file (.mp4, .3gpp.)

  • "document": Sends a document file (.pdf).

  • "contacts": Sends contact information.

  • "location": Sends a location with latitude and longitude.

  • "interactive": Sends an interactive message with reply buttons or list .

In this example, we set the "contacts" parameter.
request.contacts Yes

Only applies to the "contacs" type.

Array that contains the contact information.

Contact information options:

  • "addresses": Full contact address(es).

  • "birthday": Birthday of the contact.

  • "emails": Contact email address(es).

  • "name": Full contact name formatted.

  • "org": Contact organization information.

  • "phones": Contact phone number(s).

  • "urls": Contact URL(s).
request.contacts.
addresses		 No

Only applies to the "contacs" type.

Array of addresses associated with the contact.
request.contacts.
addresses.
city		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

City where the contact resides.
request.contacts.
addresses.
country		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Country
request.contacts.
addresses.
country_code		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Country code in ISO format (e.g., "us")
request.contacts.
addresses.
state		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

State or province (e.g., "CA").
request.contacts.
addresses.
street		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Street address.
request.contacts.
addresses.
type		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

Type of address, such as "HOME" or "WORK".
request.contacts.
addresses.
zip		 No

Only applies to the "contacs" type, and the "addresses" contact information option.

ZIP or postal code.
request.contacts.
birthday		 No

Only applies to the "contacs" type.

Contact's birthday in YYYY-MM-DD format.
request.contacts.
emails		 No

Only applies to the "contacs" type.

Array of email addresses associated with the contact.
request.contacts.
emails.
email		 No

Only applies to the "contacs" type, and the "emails" contact information option.

Email address of the contact.
request.contacts.
emails.
type		 No

Only applies to the "contacs" type, and the "emails" contact information option.

Type of email, such as "HOME" or "WORK".
request.contacts.
name		 Yes

Only applies to the "contacs" type.

Object representing the name of the contact.
request.contacts.
name.
first_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's first name.
request.contacts.
name.
formatted_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's formatted name. This will appear in the message alongside the profile arrow button.
request.contacts.
name.
last_name		 Yes

Only applies to the "contacs" type, and the "name" contact information option.

Contact's last name.
request.contacts.
org		 No

Only applies to the "contacs" type.

Object representing the organization the contact is associated with.
request.contacts.
org.
company		 No

Only applies to the "contacs" type, and the "org" contact information option.

Name of the company where the contact works.
request.contacts.
org.
department		 No

Only applies to the "contacs" type, and the "org" contact information option.

The department within the company.
request.contacts.
org.
title		 No

Only applies to the "contacs" type, and the "org" contact information option.

Contact's job title.
request.contacts.
phones		 No

Only applies to the "contacs" type.

Array of phone numbers associated with the contact.
request.contacts.
phones.
phone		 No

Only applies to the "contacs" type, and the "phones" contact information option.

WhatsApp user phone number in E.164 format.
request.contacts.
phones.
type		 No

Only applies to the "contacs" type, and the "phones" contact information option.

Type of phone number, such as "HOME" or "WORK".
request.contacts.
phones.
wa_id		 No

Only applies to the "contacs" type, and the "phones" contact information option.

WhatsApp user ID.
request.contacts.
urls		 No

Only applies to the "contacs" type.

Array of URLs associated with the contact.
request.contacts.
urls.
url		 No

Only applies to the "contacs" type, and the "urls" contact information option.

Website URL associated with the contact or their company.
request.contacts.
urls.
type		 No

Only applies to the "contacs" type, and the "urls" contact information option.

Type of website, such as "HOME" or "WORK".
request.externalId No

Alphanumeric identifier used for reporting purposes.
request.clientId No Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.
callbacks No

Indicate one or more (separated by comma) webhook URLs to notify about the status of the message delivery.That is, If you want to receive the status of the message you've sent to your subscribers, you need to specify your endpoint.

Your endpoint must have a HTTP POST access method and receive a JSON body.

The URL is the external callback where the events of the Email will be registered and published. Once an email is processed, its status will be posted to your callback URL.

To view the full list and meaning of each status, please refer to the WhatsApp Status section.

Updated about 22 hours ago