Skip to navigation
Deployment OTP Profile Errors
 
 

WhatsApp Provisioning API

Beta

The WhatsApp Manager API enables customers to deploy a WhatsApp cluster, perform One Time Password (OTP) verification, and update profile information

Download OAS 3 Definition
Improve this specification

Jump to:

Deployment »

Create and manage in-progress deployments

OTP »

Verify or resend a One Time Password (OTP)

Profile »

Update WhatsApp profile

Deployment

Create and manage in-progress deployments

Available Operations:

Provision WhatsApp deployment

This API request provisions a WhatsApp cluster. Once provisioned, the cluster progresses through the following deployment stages: INITIALIZING, CREATING_CLUSTER and CLUSTER_CREATED. When the CLUSTER_CREATED stage is reached an OTP voice call or SMS is sent to the specified number and the deployment status becomes CODE_SENT. When the OTP is received, call the Verify API to complete the process.

POST https://api.nexmo.com/v0.1/whatsapp-manager/deployments
Host https://api.nexmo.com
POST /v0.1/whatsapp-manager/deployments

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Request body application/json

country_code
string | Required

The international dialing code of the number being provisioned

number
string | Required

The WhatsApp number being provisioned.

vname_certificate
string | Required

The certificate, which you can retrieve from your WhatsApp Business dashboard.

Note this value is refreshed whenever you click the View button.

method
string | Required

The method for delivering the OTP

Must be one of: sms or voice
waba_id
string | Required

WABA ID of the WhatsApp Number

pin
string

Required if you previously set a PIN when creating a WhatsApp number.

Responses

202 Accepted.
deployment_id
string

The Deployment id

waba_id
string

The WhatsApp Business Account (WABA) ID of the WhatsApp number

country_code
string

The international dialing code of the deployment e.g. 44 for the United Kingdom.

number
string

The phone number of the deployment (minus the international dialing code) e.g. 7700900000

api_key
string

The API key associated with the deployment.

current_state
object

The current status of the deployment

title
string

The current status of the deployment.

One of: INITIALIZING, CREATING_CLUSTER, CLUSTER_CREATED, CODE_SENT, WRONG_CODE, CODE_VERIFIED, FINALIZING, READY, ERROR, DELETING or DELETED
detail
string

Description of the deployment status e.g. Invalid vname certificate

Example Request

{
  "country_code": "44",
  "number": "8675309",
  "vname_certificate": "AbCdEFGHiJK123456",
  "method": "sms",
  "waba_id": "123456789123"
}
{
  "country_code": "44",
  "number": "8675309",
  "vname_certificate": "AbCdEFGHiJK123456",
  "method": "sms",
  "waba_id": "123456789123",
  "pin": "123456"
}

Example Responses

202 400 401 403 409 
{
  "deployment_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "waba_id": "abc123",
  "country_code": "44",
  "number": "7700900000",
  "api_key": "abcd1234",
  "current_state": {
    "title": "INITIALIZING",
    "detail": "Initializing deployment"
  }
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#invalid-json",
  "title": "Invalid JSON",
  "detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#forbidden",
  "title": "Forbidden",
  "detail": "Your account does not have permission to perform this action - see https://www.vonage.com/communications-apis/contact-api/ for more details about getting signed up to send WhatsApp messages.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#number-in-use",
  "title": "Number already in use",
  "detail": "Active deployment already exists with id 21801df5-a3f6-4bd6-8b66-5bde51a909c7",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Get Deployment Status

Retrieves information about the deployment at the given deployment id.

GET https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id
Host https://api.nexmo.com
GET /v0.1/whatsapp-manager/deployments/:deployment_id

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Responses

200 The deployment.
deployment_id
string

The Deployment id

waba_id
string

The WhatsApp Business Account (WABA) ID of the WhatsApp number

country_code
string

The international dialing code of the deployment e.g. 44 for the United Kingdom.

number
string

The phone number of the deployment (minus the international dialing code) e.g. 7700900000

api_key
string

The API key associated with the deployment.

current_state
object

The current status of the deployment

title
string

The current status of the deployment.

One of: INITIALIZING, CREATING_CLUSTER, CLUSTER_CREATED, CODE_SENT, WRONG_CODE, CODE_VERIFIED, FINALIZING, READY, ERROR, DELETING or DELETED
detail
string

Description of the deployment status e.g. Invalid vname certificate

Example Responses

200 401 404 
{
  "deployment_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "waba_id": "abc123",
  "country_code": "44",
  "number": "7700900000",
  "api_key": "abcd1234",
  "current_state": {
    "title": "INITIALIZING",
    "detail": "Initializing deployment"
  }
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Delete Deployment

Delete a WhatsApp deployment

DELETE https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id
Host https://api.nexmo.com
DELETE /v0.1/whatsapp-manager/deployments/:deployment_id

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Example Responses

204 401 404 409 
No Content
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#conflict-deployment-state",
  "title": "Conflict",
  "detail": "Deployment cannot be deleted because it is in the DELETING state.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

OTP

Verify or resend a One Time Password (OTP)

Available Operations:

Resend OTP

If you do not receive the code in five minutes then you can request for it to be sent again.

POST https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/resend-otp
Host https://api.nexmo.com
POST /v0.1/whatsapp-manager/deployments/:deployment_id/resend-otp

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Request body application/json

method
string

The method for delivering the OTP

Must be one of: sms or voice

Responses

202 Code sent.
message
string
vname
string
method
string

The method the OTP resend will use.

Example Request

{
  "method": "sms"
}

Example Responses

202 400 401 404 409 429 
{
  "message": "Code sent",
  "vname": "your vname",
  "method": "sms"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#invalid-json",
  "title": "Invalid JSON",
  "detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#conflict-resend-otp",
  "title": "Deployment Completed, Resend Failed",
  "detail": "OTP not required.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#throttled",
  "title": "Throttled",
  "detail": "Exceeded rate limit for this API, please wait and try again",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Verify OTP

When a code is successfully verified, WhatsApp Manager will move the number from a CODE_VERIFIED state to a FINALIZING state where additional checks are made and it is assigned to your API Key. Once this is complete it will enter a READY state and the number is ready to use.

POST https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/verify
Host https://api.nexmo.com
POST /v0.1/whatsapp-manager/deployments/:deployment_id/verify

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Request body application/json

code
string

OTP being submitted for verification

Responses

201 OK
deployment_id
string

the id of your deployment

status
string

Example Request

{
  "code": "674639"
}

Example Responses

201 400 401 404 422 429 
{
  "deployment_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "status": "Deployment was Created"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#invalid-json",
  "title": "Invalid JSON",
  "detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#verification-failed",
  "title": "Verification Failed",
  "detail": "Deployment could not be created because the verification failed.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
  "invalid_parameters": [
    {
      "name": "code",
      "reason": "Invalid code provided."
    }
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#throttled",
  "title": "Throttled",
  "detail": "Exceeded rate limit for this API, please wait and try again",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Profile

Update WhatsApp profile

Available Operations:

Get Profile Info

Get's business profile information

GET https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/profile
Host https://api.nexmo.com
GET /v0.1/whatsapp-manager/deployments/:deployment_id/profile

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Responses

200 OK
about
string

Text to display in your profile's About section - max 139 characters.

address
string

Your business address - max 256 characters.

description
string

a description of your business - max 256 characters

email
string

Your business' email - max 128 characters

vertical
string

Your business' industry - must be recognized by WhatsApp.

One of: Automotive, Beauty, Spa and Salon, Clothing and Apparel, Education, Entertainment, Event Planning and Service, Finance and Banking, Food and Grocery, Public Service, Hotel and Lodging, Medical and Health, Non-profit, Professional Services, Shopping and Retail, Travel and Transportation, Restaurant or Other
websites
array of strings

Your business' websites maximum of 2 websites, max website length: 256

Example Responses

200 401 404 
{
  "about": "about your business",
  "address": "123 main street",
  "description": "your business description",
  "email": "you@example.com",
  "vertical": "Food and Grocery",
  "websites": [
    "https://example.com"
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Update WhatsApp Profile

Updates profile information for deployment.

PATCH https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/profile
Host https://api.nexmo.com
PATCH /v0.1/whatsapp-manager/deployments/:deployment_id/profile

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Request body application/json

Provision WhatsApp deployment and trigger OTP.

about
string | Min: 1 | Max: 139

Text to display in your profile's About section - max 139 characters.

address
string | Min: 1 | Max: 256

Your business address - max 256 characters.

description
string | Min: 1 | Max: 256

a description of your business - max 256 characters

email
string | Min: 1 | Max: 128

Your business' email - max 128 characters

vertical
string

Your business' industry - must be recognized by WhatsApp.

Must be one of: Automotive, Beauty, Spa and Salon, Clothing and Apparel, Education, Entertainment, Event Planning and Service, Finance and Banking, Food and Grocery, Public Service, Hotel and Lodging, Medical and Health, Non-profit, Professional Services, Shopping and Retail, Travel and Transportation, Restaurant or Other
websites
array of strings

Your business' websites maximum of 2 websites, max website length: 256

Responses

200 OK
about
string

Text to display in your profile's About section - max 139 characters.

address
string

Your business address - max 256 characters.

description
string

a description of your business - max 256 characters

email
string

Your business' email - max 128 characters

vertical
string

Your business' industry - must be recognized by WhatsApp.

One of: Automotive, Beauty, Spa and Salon, Clothing and Apparel, Education, Entertainment, Event Planning and Service, Finance and Banking, Food and Grocery, Public Service, Hotel and Lodging, Medical and Health, Non-profit, Professional Services, Shopping and Retail, Travel and Transportation, Restaurant or Other
websites
array of strings

Your business' websites maximum of 2 websites, max website length: 256

Example Request

{
  "about": "about your business",
  "address": "123 main street",
  "description": "your business description",
  "email": "you@example.com",
  "vertical": "Food and Grocery",
  "websites": [
    "https://example.com"
  ]
}

Example Responses

200 400 401 404 422 
{
  "about": "about your business",
  "address": "123 main street",
  "description": "your business description",
  "email": "you@example.com",
  "vertical": "Food and Grocery",
  "websites": [
    "https://example.com"
  ]
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#invalid-json",
  "title": "Invalid JSON",
  "detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#unprocessable-profile-update",
  "title": "Unprocessable Entity",
  "detail": "Description was longer than 256 characters and could not be processed.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
  "invalid_parameters": [
    {
      "name": "email",
      "reason": "Email format invalid"
    }
  ]
}

Get Profile Photo

Get's business profile photo

GET https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/profile/photo
Host https://api.nexmo.com
GET /v0.1/whatsapp-manager/deployments/:deployment_id/profile/photo

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Responses

200 OK.
image_url
string

Url where the profile photo was pulled from

Example Responses

200 401 404 
{
  "image_url": "https://www.example.com/img.png"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}

Update Profile Photo

Replaces profile photo with photo at the given URL for the deployment.

POST https://api.nexmo.com/v0.1/whatsapp-manager/deployments/:deployment_id/profile/photo
Host https://api.nexmo.com
POST /v0.1/whatsapp-manager/deployments/:deployment_id/profile/photo

Authentication

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs 		Bearer <JWT> None

Path Parameters

deployment_id
string | Required

The deployment ID

Request body application/json

URL pointing to a .png or .jpg. Image must be minimum 192px. max 640px x 640px. max 5MB.

image_url
string | Required

URL pointing to a .png or .jpg. Image must be minimum 192px. max 640px x 640px. max 5MB.

Responses

200 OK.
image_url
string

Url where the profile photo was pulled from

Example Request

{
  "image_url": "https://www.example.com/img.png"
}

Example Responses

200 400 401 404 422 
{
  "image_url": "https://www.example.com/img.png"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#invalid-json",
  "title": "Invalid JSON",
  "detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#unauthorized",
  "title": "You did not provide correct credentials.",
  "detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors#not-found",
  "title": "Not Found",
  "detail": "Deployment does not exist or you do not have access.",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}
{
  "type": "https://developer.nexmo.com/api-errors/whatsapp-provisioning#unprocessable",
  "title": "Unprocessable Entity",
  "detail": "Request was missing a waba_id and could not be processed",
  "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
  "invalid_parameters": [
    {
      "name": "url",
      "reason": "Url was not in a valid format"
    }
  ]
}

Errors

The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.

Code Details
number-in-use

Cannot use number because it's already in use by another deployment.
invalid-json

The request body did not contain valid JSON
unprocessable

Parameters were valid JSON but something was missing or wrongly formatted
unprocessable-profile-update

Parameters were valid JSON but something was missing or wrongly formatted
throttled

Too many requests have been made on this endpoint
verification-failed

Verification step failed. Either because the the provided code was incorrect or because too many attempts have been made
conflict-deployment-state

Deployment could not be modified because it is currently in a transitional state.
conflict-resend-otp

Could not resend OTP because the current state of the deployment did not allow it