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.
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? |
---|---|---|---|---|
| String | Account SID (Security Identifier). | HXAP173XXXXXXXIN | Yes |
| String | Your API Key generated by kaleyra.io. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
| String | The format in which the data is sent. | application/x-www-form-urlencoded | Yes |
| String | Channel on which message must be sent. | Yes | |
| String | A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format).
| 919XXXXXXX36 | Yes |
| 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 |
| String | Format of the message. | contacts | Yes |
| 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. | 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