Share Contact Information

POST Method

Request Format

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

curl --location 'https://api.kaleyra.io/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.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	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	HXAP173XXXXXXXXX	True
`api-key`	String	API key generated from kaleyra.io account.	Axxxxxxxxxxxxxxxxxxxxxxxxxxxx3	True
`content_type`	String	The format in which the data is sent.	application/x-www-form-urlencoded	True
`channel_name`	String	Channel on which message must be sent. For the WhatsApp channel, the only allowed value is WhatsApp.	WhatsApp	True
`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.	91XXXXXXXXXX	True
`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).	91XXXXXXXXXX	True
`message_type`	String	Format of the message.	contacts	True
`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	False

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

Parameter	Data Type	Description	Example	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	True
`zip`	String	Zip code.	94025	Optional

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

Parameter	Data Type	Description	Example	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	Example	Mandatory?
`first_name`	String	First name of the recipient.	John	Optional
`formatted_name`	String	First and last name of the recipient.	John Smith	True
`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	Example	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	Example	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.	1650XXXXXXX	Optional

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

Parameter	Data Type	Description	Example	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 202 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 about 1 month ago