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:

  1. 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.
  2. 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_domainValue
IN podapi.in.kaleyra.io
SG Podapi.kaleyra.io
EU Podapi.eu.kaleyra.io
NA podapi.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:

ParameterData TypeDescriptionExamplesMandatory?
cityStringCity name.Menlo ParkOptional
countryStringFull country name.United StatesOptional
country_codeStringTwo-letter country abbreviation.usOptional
stateStringState abbreviation.CAOptional
streetStringStreet number and name.1, Hacker WayOptional
typeStringPhone number type. Standard values are Home and Work.HomeYes
zipStringZip code.94025Optional

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

ParameterData TypeDescriptionExamplesMandatory?
emailStringEmail address.[email protected]Optional
typeStringEmail type.InternetOptional

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

ParameterData TypeDescriptionExamplesMandatory?
first_nameStringFirst name of the recipient.JohnOptional
formatted_nameStringFirst and last name of the recipient.John SmithYes
last_nameStringLast name of the recipient.SmithOptional

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

ParameterData TypeDescriptionExamplesMandatory?
companyStringName of the contact's company.InmarkOptional
departmentStringName of the contact's department.DesignOptional
titleStringContact's business title.ManagerOptional

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

ParameterData TypeDescriptionExamplesMandatory?
phoneStringPhone number of the recipient.+1 (940) XXX-1XXXOptional
typeStringPhone number type. Standard values are Home and Work.WorkOptional
wa_idStringWhatsApp ID.1650XXXXXX5Optional

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

ParameterData TypeDescriptionExamplesMandatory?
urlStringcontact URL.https://www.testing.comOptional
typeStringPhone number type. Standard values are Home and Work.HomeOptional

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."
    }
}




© 2025 Kaleyra Inc. All rights reserved.
Trademarks, logos and service marks displayed on this site are registered and unregistered trademarks of Kaleyra Inc.