Send a contacts message

Sends one or more contact cards the recipient can save to their address book or message directly. Needs an open 24-hour window.

Example

curl -X POST "$HELLO_API_URL/v1/<your-phone-number-id>/messages" \
  -H "Authorization: Bearer $HELLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919999999999",
    "type": "contacts",
    "contacts": [
      {
        "name": {
          "formatted_name": "Priya Sharma",
          "first_name": "Priya",
          "last_name": "Sharma"
        },
        "phones": [
          { "phone": "+919812345678", "type": "WORK" }
        ]
      }
    ]
  }'

Note that contacts is an array at the top level of the request, not an object.

Response

202 Accepted (queued), or 200 with ?sync=true once WhatsApp accepts it. See Send a message.

Fields

Field	Type	Required	Description
contacts	array	Yes	One or more contact cards
contacts[].name.formatted_name	string	Yes	Full name as displayed
contacts[].name.first_name	string	No	First name
contacts[].name.last_name	string	No	Last name
contacts[].phones[].phone	string	Yes, per phone	Phone number, ideally in + international format
contacts[].phones[].type	string	No	Label such as CELL, MAIN, HOME or WORK

Common errors

Status	code	Cause
403	OUTSIDE_24H_WINDOW	The recipient’s 24-hour window is closed
400	VALIDATION_ERROR	contacts is missing, empty or not an array
422	SEND_FAILED	(?sync=true only) WhatsApp rejected the send