WhatsApp Registration

POST Method

The WhatsApp Registration API is used for submitting the initial WhatsApp Request Access. This API enables the user to register their first WhatsApp number on the Kaleyra platform.

The Request Access API contains the following options:

  • Account Name
  • Business Manager ID
  • Screenshot of Business Manager ID (Upload Image)
  • Number Details
    a) Display Name
    b) Phone Number
    c) Incoming URL (Optional)

📘

Note:

  • This API allows only registration if the account does not have an active WhatsApp channel (approved business WABA id).
  • The validation is the same as in the User Interface.

Base URL

https://api.kaleyra.io/v1/

To Register for WhatsApp, perform the following steps:

1. Signup or Login to Kaleyra.io and create your API key.

Before you get started, sign up for a Kaleyra.io account for free and create an API key.

📘

Note:

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in Kaleyra.io.

2. API command for WhatsApp Registration.

Request Format - POST

To register WhatsApp, use the /WhatsApp/activation endpoints.

curl --location --request POST '{{url}}/v1/{{sid}}/whatsapp/activation' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: <CONTENT_TYPE>' \
--data-raw '{
    "display_name": <DISPLAY_NAME>,
    "wa_number": <WA_NUMBER>,
    "business_id": <BUSINESS_ID>,
    "business_name": <BUSINESS_NAME>,
    "business_certificate": <BUSINESS_CERTIFICATE>
    }'

Parameters and Variables

The following table displays the parameter and variables used:

Parameter

Variable

Description

Example

Mandatory

SID

String

Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key.

HXXXXXXX071US

True

API_KEY

String

Your API Key generated by Kaleyra.io.

Ac4XXXXX21f

True

CONTENT_TYPE

Alphanumeric

Indicates the format of the content the API will be processing.

application/JSON

True

DISPLAY_NAME

String

Specifies the WhatsApp number display name.

Test

True

WA_NUMBER

String

Specifies the registered WhatsApp number in E164 format.

+13236xxxxx7

True

BUSINESS_ID

Integer

Specifies the WhatsApp business ID provided by Facebook.

123

True

BUSINESS_NAME

String

Specifies the business name.

Test Business

True

BUSINESS_CERTIFICATE

File

Specifies the business certificate provided by Facebook.

NA

True

Response Format

Success Format

This section provides you the successful JSON response format.

HTTP Response:
{
    "code": "I102",
    "message": "Activation request created successfully.",
    "data": [
        {
            "business_details": {
                "id": 2,
                "company_id": "ZXXX32d",
                "business_id": "123XXXX891",
                "business_name": "kaleyra",
                "certificate_id": 2521,
                "status": 2,
                "namespace": "30e1XXX6_bXX8_c216_cd8d_166XXXX02e6d",
                "created_at": "157XXXX696",
                "modified_at": "1XX04XX895",
                "created_by": "185XXXX647",
                "modified_by": "185XXXX647",
                "waba_id": "2090XXXXX0974XX3"
            },
            "phone_number": {
                "created_by": "18XXXX5647",
                "created_at": "16XXXX7895",
                "company_id": "Z82XXXd",
                "name": "xyz",
                "incoming_url": "",
                "phone_number": "+13236xxxxx7",
                "country": "pratappur, madhya pradesh",
                "status": 2,
                "iso_code": "IN",
                "id": 131
            },
            "template": ""
        }
    ],
    "error": {}
}

Failure Response

The business_certificate field is a mandatory field and cannot be empty. You need to upload the WhatsApp business certificate provided by Facebook.

{
    "code": "E939",
    "message": "Failed to submit request for Whatsapp account activation.",
    "data": [],
    "error": {
        "code": "E413",
        "type": "VALIDATION_ERROR",
        "parameter": "business_certificate",
        "message": "business_certificate field is required and cannot be empty.",
        "reference": ""
    }
}

The business_certificate must be a file of type jpeg, jpg, pdf, or png. The business certificate needs to be an image of type PNG, JPG, JPEG, or PDF.

{
    "code": "E939",
    "message": "Failed to submit request for Whatsapp account activation.",
    "data": [],
    "error": {
        "code": "E413",
        "type": "VALIDATION_ERROR",
        "parameter": "business_certificate",
        "message": "The business_certificate must be a file of type: jpeg,jpg,pdf,png.",
        "reference": ""
    }
}

This account already has submitted a request for WhatsApp activation. You can submit a business WhatsApp activation request only once per account.

{
    "code": "E939",
    "message": "Failed to submit request for Whatsapp account activation.",
    "data": [],
    "error": {
        "code": "E937",
        "message": "This account already has submitted a request for WhatsApp activation.",
        "data": []
    }
}

Sample Request

The following code is a sample request:

curl --location --request POST '{url}/v1/{SID}/whatsapp/activation' \
--header 'api-key: <API_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "display_name":<xyz>,
    "wa_number":"+13236xxxxx7",
    "business_id": "12XXX67891",
    "business_name="Kaleyra",
    "[email protected]"<file_path>",
    }'

Error Code

The following table provides information about the error codes you would receive when executing the Add WhatsApp Registration API.

Error Code

Description

E413

business_certificate field is required and cannot be empty.

E937

This account already has submitted a request for WhatsApp activation.


Did this page help you?