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/><SID>

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. 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 must complete the KYC to access all the features in Kaleyra.io.

  1. 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:

ParameterVariableDescriptionExampleMandatory
SIDStringAccount SID (Security Identifier). Generated by Kaleyra.io while creating an API key.HXXXXXXX071USTrue
API_KEYStringYour API Key generated by Kaleyra.io.Ac4XXXXX21fTrue
CONTENT_TYPEAlphanumericIndicates the format of the content the API will be processing.application/JSONTrue
DISPLAY_NAMEStringSpecifies the WhatsApp number display name.TestTrue
WA_NUMBERStringSpecifies the registered WhatsApp number in E164 format.+13236xxxxx7True
BUSINESS_IDIntegerSpecifies the WhatsApp business ID provided by Facebook.123True
BUSINESS_NAMEStringSpecifies the business name.Test BusinessTrue
BUSINESS_CERTIFICATEFileSpecifies the business certificate provided by Facebook.NATrue

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",
    "business_certificate=@"<file_path>",
    }'

Error Code

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

Error CodeDescription
E413business_certificate field is required and cannot be empty.
E937This account already has submitted a request for WhatsApp activation.