Share Contact Information

POST and GET Methods

Description

The end user can share any contact information to single person or a group of people from your WhatsApp using this API.

Base URL

<https://api.kaleyra.io/v1/><SID>

To share contact information on WhatsApp, follow the below steps:

  1. Sign in to Kaleyra.io and create your API key.

Refer to the Create an API Key page for steps to create your API key. To view the API Key and the SID, see View API Key and SID.

📘

Note:

After you sign up, your account will be on the trial version. You need to complete the KYC to access all the features of Kalyera Cloud.

  1. API command to share contact information

Request Format

To send your first SMS, use the /messages endpoints.

curl -X POST "https://https://api.kaleyra.io/v1/<SID>/messages" \
     -H "api-key: <API_KEY>" \
     -H "Content-Type: <CONTENT_TYPE>" \
     -d "channel=<CHANNEL_NAME>" \
     -d "to=<TO_NUMBER>" \
     -d "from=<FROM_NUMBER>" \
     -d "type=<MESSAGE_TYPE>" \
     -d 'param_contacts={"name": {  "first_name": "<FIRST_NAME>","formatted_name":"    <FORMATTED_NAME>", "last_name": "<LAST_NAME>" },"phones": [ { "phone": "<PHONE_NUMBER>",   "type": "<NUMBER_TYPE>"}]}' \
     -d "callback_url=<CALLBACK_URL>"

📘

Note:

Ensure to replace the parameter values with the proper inputs in the above code.

Parameters and Variables

The below table displays the parameters and variables used:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier)HXXXXXXX071USTrue
CONTENT_TYPEStringThe format in which the data is sent.application/x-www-form-urlencodedTrue
API_KEYStringAPI Key generated by Kaleyra.io.Ac4XXXXX21fTrue
TO_NUMBERIntegerA 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.
+1202XXXXXXXTrue
MESSAGE_TYPEStringFormat of the message.contactsTrue
CHANNEL_NAMEStringChannel on which the message should be sent.WhatsAppTrue
FROM_NUMBERIntegerThe 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).+1202XXXXXXXTrue
FIRST_NAMEStringFirst name of the recipientJohnFalse
FORMATTED_NAMEStringFirst and last name of the recipientJohn DoeFalse
LAST_NAMEStringLast name of the recipientDoeFalse
PHONE_NUMBERIntegerPhone number of the recipient+1202XXXXXXXTrue
NUMBER_TYPEStringPhone number typeHomeFalse
CALLBACK_URLStringThe URL that Kalyera.io should send information to when your number receives a response. This URL can be accessed publicly.https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345cFalse
  1. Response Format

This section provides you the successful JSON response format.

Success Response

{
    "id": "8xxxxxxx-fxxx-4xxx-axxx-exxxxxxxxxxx",
    "type": "contacts",
    "body": null,
    "createdDateTime": "2020-12-10 10:16:13+00:00",
    "totalCount": 1,
    "data": [
        {
            "message_id": "8xxxxxxx-fxxx-4xxx-axxx-exxxxxxxxxxx:x",
            "recipient": "91xxxxxxxxxx"
        }
    ],
    "error": {}
}

📘

Note:

In case of error, ensure that the above replaceable values are correct. See Standard Error Codes

Sample Request

curl -X POST "https://https://api.kaleyra.io/v1/HXXXXXXX071US/messages" \
     -H "api-key: Ac4XXXXX21f" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "channel=whatsapp" \
     -d "to=+1XXXXXXXXXX" \
     -d "from=+1202XXXXXXX" \
     -d "type=contacts" \
     -d 'param_contacts={"name": {  "first_name": "John","formatted_name":"John Doe", "last_name": "Doe" },"phones": [ { "phone": "+1202XXXXXXX", "type": "Home"}]}' \
     -d "callback_url=https://webhook.site/89b43b12-b889-4f66-8ebf-3379b4b3345c"