Share Contact Information

POST Method

You can share any contact information with a single person or a group of people from your WhatsApp using this API.

To share the contact information on WhatsApp, perform the following steps:

Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra.io.
To set up a WhatsApp account on kaleyra.io, see: Manual Signup and Embeded Signup.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domain	Value
IN pod	api.in.kaleyra.io
SG Pod	api.kaleyra.io
EU Pod	api.eu.kaleyra.io
NA pod	api.na.kaleyra.ai

API request to share contact information

To share the contact information on WhatsApp, use the /messages endpoint.

Request Format

The following is the request format to share the contact information on WhatsApp:

curl --location 'https://<api_domain>/v1/<sid>/messages' \
--header 'api-key: <api_key>' \
--header 'content-type: <content_type>' \
--data-urlencode 'channel=<channel_name>' \
--data-urlencode 'to=<to_number>' \
--data-urlencode 'from=<from_number>' \
--data-urlencode 'type=<message_type>' \
--data-urlencode 'param_contacts={
"addresses": [
{
"city": "<city>",
"country": "<country>",
"country_code": "<country_code>",
"state": "<state>",
"street": "<street>",
"type": "<type>",
"zip": "<zip>"
},
{
"city": "<city>",
"country": "<country>",
"country_code": "<country_code>",
"state": "<state>",
"street": "<street>",
"type": "<type>",
"zip": "<zip>"
}
],
"emails": [
{
"email": "<email1>",
"type": "<type>"
},
{
"email": "<email2>",
"type": "<type>"
}
],
"ims": [],
"name": {
"first_name": "<first_name>",
"formatted_name": "<formatted_name>",
"last_name": "<last_name>"
},
"org": {
"company": "<company>",
"department": "<department>",
"title": "<title>"
},
"phones": [
{
"phone": "<phone_number1>",
"type": "<type>"
},
{
"phone": "<phone_number2>",
"type": "<type>",
"wa_id": "<wa_id>"
}
],
"urls": [
{
"type": "<type>",
"url": "<url>"
}
]
}
 ' \
--data-urlencode 'callback_url=<callback_url>'

Sample Request Format

The following is the sample request format to share the contact information on WhatsApp:

curl --location 'https://api.in.kaleyra.io/v1/HXAP173XXXXXXXXX/messages' \
--header 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
--header 'content-type: application/x-www-form-urlencoded' \
--data-urlencode 'channel=whatsapp' \
--data-urlencode 'to=91XXXXXXXXXX' \
--data-urlencode 'from=9180XXXXXXXX' \
--data-urlencode 'type=contacts' \
--data-urlencode 'param_contacts={
"addresses": [
{
"city": "Menlo Park",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "1 Hacker Way",
"type": "HOME",
"zip": "94XXX"
},
{
"city": "Dallas",
"country": "United States",
"country_code": "us",
"state": "CA",
"street": "200 Jefferson Dr",
"type": "WORK",
"zip": "940XX"
}
],
"emails": [
{
"email": "[email protected]",
"type": "INTERNET"
},
{
"email": "[email protected]",
"type": "INTERNET"
}
],
"ims": [],
"name": {
"first_name": "John",
"formatted_name": "John Smith",
"last_name": "Smith"
},
"org": {
"company": "Inmark",
"department": "Design",
"title": "Manager"
},
"phones": [
{
"phone": "+1 (940) 555-1XXX",
"type": "HOME"
},
{
"phone": "+1 (650) 555-1XXX",
"type": "WORK",
"wa_id": "1650XXXXXX5"
}
],
"urls": [
{
"type": "WORK",
"url": "https://www.testing.com"
}
]
}
 ' \
--data-urlencode 'callback_url=https://teams.microsoft.com/l/message/19:cc6XXXff-cc2e-4XX9-851a-5bfe0XXXX60b_e2297X0d-5dXX-4aXX-8XXX-0XXbdXXXXXXb@unq.gbl.XXXXXX/17223XXXXX150?context=%7B%22contextType%22%3XXXXXXXXXA%7D'

Parameter and Data Types

The following is the list of parameters and data types supported to share the contact information:

Parameter	Variable	Description	Examples	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP173XXXXXXXIN	Yes
`api_key`	String	Your API Key generated by kaleyra.io.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3	Yes
`content_type`	String	The format in which the data is sent.	application/x-www-form-urlencoded	Yes
`channel_name`	String	Channel on which message must be sent. For the WhatsApp channel, the only allowed value is WhatsApp.	WhatsApp	Yes
`to_number`	String	A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format). Note:* You can add multiple recipients separated by the comma.	919XXXXXXX36	Yes
`from_number`	String	The WhatsApp business number registered with Kaleyra.io from which the message is to be sent. Ensure the number is prefixed with the country code. (E164 format).	9180XXXXX681	Yes
`message_type`	String	Format of the message.	contacts	Yes
`callback_url`	String	Specifies the callback URL to receive notifications regarding the WhatsApp message status (sent, delivered, read, and failed). For more information related to callback profiles, see the Callback profiles page. The URL can be accessed publicly. Click here for an example.	https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c	No

The following table describes the different attributes used for the addresses object:

Parameter	Data Type	Description	Examples	Mandatory?
`city`	String	City name.	Menlo Park	Optional
`country`	String	Full country name.	United States	Optional
`country_code`	String	Two-letter country abbreviation.	us	Optional
`state`	String	State abbreviation.	CA	Optional
`street`	String	Street number and name.	1, Hacker Way	Optional
`type`	String	Phone number type. Standard values are Home and Work.	Home	Yes
`zip`	String	Zip code.	94025	Optional

The following table describes the different attributes used for the emails object:

Parameter	Data Type	Description	Examples	Mandatory?
`email`	String	Email address.	[email protected]	Optional
`type`	String	Email type.	Internet	Optional

The following table describes the different attributes used for the name object:

Parameter	Data Type	Description	Examples	Mandatory?
`first_name`	String	First name of the recipient.	John	Optional
`formatted_name`	String	First and last name of the recipient.	John Smith	Yes
`last_name`	String	Last name of the recipient.	Smith	Optional

The following table describes the different attributes used for the org object:

Parameter	Data Type	Description	Examples	Mandatory?
`company`	String	Name of the contact's company.	Inmark	Optional
`department`	String	Name of the contact's department.	Design	Optional
`title`	String	Contact's business title.	Manager	Optional

The following table describes the different attributes used for the phone object:

Parameter	Data Type	Description	Examples	Mandatory?
phone	String	Phone number of the recipient.	+1 (940) XXX-1XXX	Optional
type	String	Phone number type. Standard values are Home and Work.	Work	Optional
wa_id	String	WhatsApp ID.	1650XXXXXX5	Optional

The following table describes the different attributes used for the urls object:

Parameter	Data Type	Description	Examples	Mandatory?
url	String	contact URL.	https://www.testing.com	Optional
type	String	Phone number type. Standard values are Home and Work.	Home	Optional

Sample Success Response

The following success message appears with the status 200 Accepted:

{
    "id": "2468XXX6-18bc-49XX-b7e4-dbXXXXXd6f6d",
    "type": "contacts",
    "body": null,
    "createdDateTime": "2024-08-08 06:11:11+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "2468XXXc-18bc-49XX-b7e4-dbd6f8XXXXX0:0",
            "recipient": "919360XXXXX9"
        }
    ],
    "error": {
        "msg": "Callback not initiated as the URL is not Whitelisted."
    }
}

Updated 6 days ago

What’s Next