WhatsApp Senders

A WhatsApp Sender is also referred to as a "Business Profile" or a WhatsApp channel. The WhatsApp Sender endpoint allows you to create a Sender through Meta's Embedded sign up. A Sender must be provisioned for you as a consumer of the WhatsApp API to send messages to your end users.

List all senders in project GA 

Returns a paginated list of senders for the specified project. If no page token is supplied then the first `50` will be returned.
SecurityBasic or OAuth2.0
Request
path Parameters
projectId
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

query Parameters
pageToken
string

The page token if retrieving the next page from a previous query.

pageSize
number [ 1 .. 100 ]

The page size requested.

filterStates
Array of strings (WhatsappSenderStatesEnum)

Optionally query for sender by states.

Items Enum: "ACTIVE" "IN_PROGRESS" "INACTIVE" "PENDING_VERIFICATION" "SUSPENDED" "ERROR"
filterStatuses
Array of strings (WhatsappSenderStatusesEnum)

Optionally query for sender by statuses.

Items Enum: "DRAFT" "ERROR" "IN_PROGRESS" "REJECTED"
Responses
200

List of senders

Response Schema: application/json
totalSize
required
number

Total size of the entries matching the search query.

pageSize
required
number

Requested size of the page.

required
Array of objects (WhatsappSenderDto)
previousPageToken
string

Encoded token to use in list request to fetch previous batch of entries.

nextPageToken
string

Encoded token to use in list request to fetch next batch of entries.

400

BadRequest

401

Unauthorized

404

NotFound

500

InternalServerError

get/v1/projects/{projectId}/whatsapp/senders
Request samples 
Response samples 
application/json
Response with senders.



{
  • "totalSize": 2,
  • "pageSize": 50,
  • "senders": [
    • {
      },
    • {
      }
    ]
}
Create sender for project GA 
Creates a sender for a project. The possible combinations of region, business manager and hosting type are the following:






Region

SINCH_BR
SINCH_MX
SINCH_UK





BR
Cloud API (ES)
✅ Supported
✅ Supported
❌ Unsupported





Cloud API ( OBO )
✅ Supported
✅ Supported
❌ Unsupported




EU
Cloud API (ES)
❌ Unsupported
❌ Unsupported
✅ Supported





Cloud API ( OBO )
❌ Unsupported
❌ Unsupported
✅ Supported




US
Cloud API (ES)
✅ Supported
✅ Supported
✅ Supported





Cloud API ( OBO )
✅ Supported
✅ Supported
✅ Supported





SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
Request Body schema: application/json
required
Sender data


One of:
wabaId
required
string
WhatsApp Business Account that will be connected to the created sender. If left empty, we will try to find the WhatsApp Business Account using your projectId.


 
phoneNumberId
required
string
Phone number ID linked to the WhatsApp Business Account.


 
region
string
Region sender is provisioned in.


 Enum: "BR" "EU" "US"  
metaLocalStorage
string
Region sender store the data in Meta.


 Enum: "AE" "AU" "BH" "BR" "CA" "CH" "DE" "GB" "ID" "IN" "JP" "KR" "SG" "US" "ZA"  
businessManager
string
Business manager.


 Enum: "SINCH_BR" "SINCH_MX" "SINCH_UK"  
Responses 
201
Sender


Response Schema: application/json
id
required
string
The unique ID of the sender.


 
region
required
string
Region sender is provisioned in.


 Enum: "BR" "EU" "US" "UNRECOGNIZED"  
metaLocalStorage
required
string
Region sender store the data in Meta.


 Enum: "AE" "AU" "BH" "BR" "CA" "CH" "DE" "GB" "ID" "IN" "JP" "KR" "SG" "US" "ZA" "UNRECOGNIZED" "UNSPECIFIED"  
cloudApi
required
boolean
 Deprecated 
True if the sender is hosted in WhatsApp Cloud API.


 
businessManager
required
string
Business manager.


 Enum: "SINCH_AMERICA" "SINCH_BR" "SINCH_MX" "SINCH_SEP" "SINCH_UK" "UNRECOGNIZED"  
compatibleRegions
required
Array of strings (WhatsappRegions)   unique 
Conversation API app regions the sender can be used for.


Items Enum: "br" "eu" "us"  
state
string
The current state of the sender.


 Enum: "ACTIVE" "IN_PROGRESS" "INACTIVE" "PENDING_VERIFICATION" "SUSPENDED" "ERROR"  
object
Any pending changes to the sender.


 
object
Sender details and information.


 
conversationApiApp
string
 Deprecated 
If set, the Conversation API App ID the sender is connected to.


 
object
If set, the details of the Conversation API App the sender is connected to.


 
maxTps
number
Maximum sender TPS.


 
qualityRating
string
Current quality rating of the sender.


 Enum: "GREEN" "RED" "YELLOW" "UNKNOWN" "UNRECOGNIZED"  
dailyLimit
string
Current daily message limit of the sender.


 Enum: "NOT_SET" "TIER_100K" "TIER_10K" "TIER_1K" "TIER_250" "TIER_50" "TIER_UNLIMITED" "UNRECOGNIZED"  
bearerToken
string
Bearer token of the sender. The bearer token is needed to connect the sender to a Conversation API App.


 
created
string
The UTC Date Time in ISO 8601 for when the sender was created.


 
modified
string
The UTC Date Time in ISO 8601 for when the sender was last modified.


 
countryCode
string
Country code of sender phone number.


 
phoneNumber
string
Sender phone number without country code.


 
numberProvider
string
Provider for phone number.


 Enum: "CUSTOMER" "SINCH" "UNRECOGNIZED"  
wabaBanState
string
 Deprecated 
Please use get account endpoint for this information.


 Enum: "DISABLE" "REINSTATE" "SCHEDULE_FOR_DISABLE" "UNRECOGNIZED"  
wabaBanDate
string
 Deprecated 
Please use get account endpoint for this information.


 
400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


500
InternalServerError


Callbacks 
postComment on sender
postSender completed
postSender inactive
postSender in pending verification
postSender in rejected
postSender in error
postDaily limit changed for Sender
postQuality rating changed for Sender
post/v1/projects/{projectId}/whatsapp/senders
Request samples 
application/json
    Example body request to create an ES.
    



{
  • "region": "EU",
  • "metaLocalStorage": "DE",
  • "wabaId": "11111111111111",
  • "phoneNumberId": "222222222222222"
}
Response samples 
application/json
Response when successfully creating a sender.



{
  • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
  • "changes": {
    • "status": "IN_PROGRESS",
    • "details": {}
    },
  • "created": "2023-01-19T13:11:08.204Z",
  • "modified": "2023-01-19T13:11:08.204Z",
  • "region": "EU",
  • "metaLocalStorage": "DE",
  • "conversationApiApp": "4CF9CE97504C4A468F4610919D17ECC1",
  • "conversationApiAppDetails": {
    • "id": "4CF9CE97504C4A468F4610919D17ECC1",
    • "projectId": "ea026751-3edf-40a9-ad93-1b382bd60a78",
    • "region": "EU"
    },
  • "maxTps": 10,
  • "qualityRating": "GREEN",
  • "dailyLimit": "NOT_SET",
  • "bearerToken": "aaaaAAAA.bbbbBBBB.ccccCCCC",
  • "cloudApi": true,
  • "countryCode": "48",
  • "phoneNumber": "777777777",
  • "numberProvider": "CUSTOMER",
  • "businessManager": "SINCH_UK",
  • "compatibleRegions": [
    • "eu",
    • "us"
    ]
}
Callback payload samples 
application/json
{
  • "type": "WHATSAPP_SENDER_COMMENT_ADDED",
  • "payload": {
    • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
    • "state": "INACTIVE",
    • "details": {},
    • "created": "2023-01-19T13:11:08.204Z",
    • "modified": "2023-01-19T13:11:08.204Z",
    • "region": "EU",
    • "metaLocalStorage": "DE",
    • "conversationApiApp": "4CF9CE97504C4A468F4610919D17ECC1",
    • "conversationApiAppDetails": {
      },
    • "maxTps": 10,
    • "qualityRating": "GREEN",
    • "dailyLimit": "NOT_SET",
    • "bearerToken": "aaaaAAAA.bbbbBBBB.ccccCCCC",
    • "cloudApi": true,
    • "countryCode": "48",
    • "phoneNumber": "777777777",
    • "numberProvider": "CUSTOMER",
    • "businessManager": "SINCH_UK",
    • "compatibleRegions": [
      ]
    },
  • "comment": "Example comment"
}
Get sender for project GA 
Returns a sender for a project.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Responses 
200
Sender


Response Schema: application/json
id
required
string
The unique ID of the sender.


 
region
required
string
Region sender is provisioned in.


 Enum: "BR" "EU" "US" "UNRECOGNIZED"  
metaLocalStorage
required
string
Region sender store the data in Meta.


 Enum: "AE" "AU" "BH" "BR" "CA" "CH" "DE" "GB" "ID" "IN" "JP" "KR" "SG" "US" "ZA" "UNRECOGNIZED" "UNSPECIFIED"  
cloudApi
required
boolean
 Deprecated 
True if the sender is hosted in WhatsApp Cloud API.


 
businessManager
required
string
Business manager.


 Enum: "SINCH_AMERICA" "SINCH_BR" "SINCH_MX" "SINCH_SEP" "SINCH_UK" "UNRECOGNIZED"  
compatibleRegions
required
Array of strings (WhatsappRegions)   unique 
Conversation API app regions the sender can be used for.


Items Enum: "br" "eu" "us"  
state
string
The current state of the sender.


 Enum: "ACTIVE" "IN_PROGRESS" "INACTIVE" "PENDING_VERIFICATION" "SUSPENDED" "ERROR"  
object
Any pending changes to the sender.


 
object
Sender details and information.


 
conversationApiApp
string
 Deprecated 
If set, the Conversation API App ID the sender is connected to.


 
object
If set, the details of the Conversation API App the sender is connected to.


 
maxTps
number
Maximum sender TPS.


 
qualityRating
string
Current quality rating of the sender.


 Enum: "GREEN" "RED" "YELLOW" "UNKNOWN" "UNRECOGNIZED"  
dailyLimit
string
Current daily message limit of the sender.


 Enum: "NOT_SET" "TIER_100K" "TIER_10K" "TIER_1K" "TIER_250" "TIER_50" "TIER_UNLIMITED" "UNRECOGNIZED"  
bearerToken
string
Bearer token of the sender. The bearer token is needed to connect the sender to a Conversation API App.


 
created
string
The UTC Date Time in ISO 8601 for when the sender was created.


 
modified
string
The UTC Date Time in ISO 8601 for when the sender was last modified.


 
countryCode
string
Country code of sender phone number.


 
phoneNumber
string
Sender phone number without country code.


 
numberProvider
string
Provider for phone number.


 Enum: "CUSTOMER" "SINCH" "UNRECOGNIZED"  
wabaBanState
string
 Deprecated 
Please use get account endpoint for this information.


 Enum: "DISABLE" "REINSTATE" "SCHEDULE_FOR_DISABLE" "UNRECOGNIZED"  
wabaBanDate
string
 Deprecated 
Please use get account endpoint for this information.


 
400
BadRequest


401
Unauthorized


404
NotFound


500
InternalServerError


get/v1/projects/{projectId}/whatsapp/senders/{senderId}
Request samples 
Response samples 
application/json
Response with a sender.



{
  • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
  • "state": "ACTIVE",
  • "details": {},
  • "created": "2023-01-19T13:11:08.204Z",
  • "modified": "2023-01-19T13:11:08.204Z",
  • "region": "EU",
  • "metaLocalStorage": "DE",
  • "conversationApiApp": "4CF9CE97504C4A468F4610919D17ECC1",
  • "conversationApiAppDetails": {
    • "id": "4CF9CE97504C4A468F4610919D17ECC1",
    • "projectId": "ea026751-3edf-40a9-ad93-1b382bd60a78",
    • "region": "EU"
    },
  • "maxTps": 10,
  • "qualityRating": "GREEN",
  • "dailyLimit": "NOT_SET",
  • "bearerToken": "aaaaAAAA.bbbbBBBB.ccccCCCC",
  • "cloudApi": true,
  • "countryCode": "48",
  • "phoneNumber": "777777777",
  • "numberProvider": "CUSTOMER",
  • "businessManager": "SINCH_UK",
  • "compatibleRegions": [
    • "eu",
    • "us"
    ]
}
Delete sender for project GA 
Marks a sender for removal. Once requested the sender will be active for 30 days to send final messages. After 30 days it will be removed.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Responses 
204
Sender deleted


400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


500
InternalServerError


delete/v1/projects/{projectId}/whatsapp/senders/{senderId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "project_not_initialized",
  • "message": "Project not initialized for WhatsApp.",
  • "resolution": "Verify that the project ID is correct and that it has been onboarded for WhatsApp."
}
Updates a sender in project GA 
Updates a sender in project.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Request Body schema: application/json
required
Supported sender fields to update


status
string
 Default:  "DRAFT"
Create as draft or submit. Defaults to draft.


 Enum: "DRAFT" "SUBMIT"  
object
 
Responses 
200
Updated sender in project


Response Schema: application/json
id
required
string
The unique ID of the sender.


 
region
required
string
Region sender is provisioned in.


 Enum: "BR" "EU" "US" "UNRECOGNIZED"  
metaLocalStorage
required
string
Region sender store the data in Meta.


 Enum: "AE" "AU" "BH" "BR" "CA" "CH" "DE" "GB" "ID" "IN" "JP" "KR" "SG" "US" "ZA" "UNRECOGNIZED" "UNSPECIFIED"  
cloudApi
required
boolean
 Deprecated 
True if the sender is hosted in WhatsApp Cloud API.


 
businessManager
required
string
Business manager.


 Enum: "SINCH_AMERICA" "SINCH_BR" "SINCH_MX" "SINCH_SEP" "SINCH_UK" "UNRECOGNIZED"  
compatibleRegions
required
Array of strings (WhatsappRegions)   unique 
Conversation API app regions the sender can be used for.


Items Enum: "br" "eu" "us"  
state
string
The current state of the sender.


 Enum: "ACTIVE" "IN_PROGRESS" "INACTIVE" "PENDING_VERIFICATION" "SUSPENDED" "ERROR"  
object
Any pending changes to the sender.


 
object
Sender details and information.


 
conversationApiApp
string
 Deprecated 
If set, the Conversation API App ID the sender is connected to.


 
object
If set, the details of the Conversation API App the sender is connected to.


 
maxTps
number
Maximum sender TPS.


 
qualityRating
string
Current quality rating of the sender.


 Enum: "GREEN" "RED" "YELLOW" "UNKNOWN" "UNRECOGNIZED"  
dailyLimit
string
Current daily message limit of the sender.


 Enum: "NOT_SET" "TIER_100K" "TIER_10K" "TIER_1K" "TIER_250" "TIER_50" "TIER_UNLIMITED" "UNRECOGNIZED"  
bearerToken
string
Bearer token of the sender. The bearer token is needed to connect the sender to a Conversation API App.


 
created
string
The UTC Date Time in ISO 8601 for when the sender was created.


 
modified
string
The UTC Date Time in ISO 8601 for when the sender was last modified.


 
countryCode
string
Country code of sender phone number.


 
phoneNumber
string
Sender phone number without country code.


 
numberProvider
string
Provider for phone number.


 Enum: "CUSTOMER" "SINCH" "UNRECOGNIZED"  
wabaBanState
string
 Deprecated 
Please use get account endpoint for this information.


 Enum: "DISABLE" "REINSTATE" "SCHEDULE_FOR_DISABLE" "UNRECOGNIZED"  
wabaBanDate
string
 Deprecated 
Please use get account endpoint for this information.


 
400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


500
InternalServerError


Callbacks 
postComment on sender
postSender completed
postSender inactive
postSender in pending verification
postSender in rejected
postSender in error
postDaily limit changed for Sender
postQuality rating changed for Sender
patch/v1/projects/{projectId}/whatsapp/senders/{senderId}
Request samples 
application/json
  Example body request to update a sender.
  



{}
Response samples 
application/json
Response when successfully update a sender.



{
  • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
  • "state": "ACTIVE",
  • "changes": {
    • "status": "IN_PROGRESS",
    • "details": {}
    },
  • "details": {},
  • "created": "2023-01-19T13:11:08.204Z",
  • "modified": "2023-01-19T13:11:08.204Z",
  • "region": "EU",
  • "metaLocalStorage": "DE",
  • "conversationApiApp": "4CF9CE97504C4A468F4610919D17ECC1",
  • "conversationApiAppDetails": {
    • "id": "4CF9CE97504C4A468F4610919D17ECC1",
    • "projectId": "ea026751-3edf-40a9-ad93-1b382bd60a78",
    • "region": "EU"
    },
  • "maxTps": 10,
  • "qualityRating": "GREEN",
  • "dailyLimit": "NOT_SET",
  • "bearerToken": "aaaaAAAA.bbbbBBBB.ccccCCCC",
  • "cloudApi": true,
  • "countryCode": "48",
  • "phoneNumber": "777777777",
  • "numberProvider": "CUSTOMER",
  • "businessManager": "SINCH_UK",
  • "compatibleRegions": [
    • "eu",
    • "us"
    ]
}
Callback payload samples 
application/json
{
  • "type": "WHATSAPP_SENDER_COMMENT_ADDED",
  • "payload": {
    • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
    • "state": "INACTIVE",
    • "details": {},
    • "created": "2023-01-19T13:11:08.204Z",
    • "modified": "2023-01-19T13:11:08.204Z",
    • "region": "EU",
    • "metaLocalStorage": "DE",
    • "conversationApiApp": "4CF9CE97504C4A468F4610919D17ECC1",
    • "conversationApiAppDetails": {
      },
    • "maxTps": 10,
    • "qualityRating": "GREEN",
    • "dailyLimit": "NOT_SET",
    • "bearerToken": "aaaaAAAA.bbbbBBBB.ccccCCCC",
    • "cloudApi": true,
    • "countryCode": "48",
    • "phoneNumber": "777777777",
    • "numberProvider": "CUSTOMER",
    • "businessManager": "SINCH_UK",
    • "compatibleRegions": [
      ]
    },
  • "comment": "Example comment"
}
Lists activities on sender GA 
Paginated list of activities for sender. Ordered from the most recent one to the oldest one.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
query Parameters
pageToken
string
The page token if retrieving the next page from a previous query.


 
pageSize
number  [ 1 .. 100 ] 
The page size requested.


 
Responses 
200
Recent activities on sender


Response Schema: application/json
totalSize
required
number
Total size of the entries matching the search query.


 
pageSize
required
number
Requested size of the page.


 
required
Array of objects (WhatsappSenderNotificationDto) 
 
previousPageToken
string
Encoded token to use in list request to fetch previous batch of entries.


 
nextPageToken
string
Encoded token to use in list request to fetch next batch of entries.


 
400
BadRequest


401
Unauthorized


404
NotFound


500
InternalServerError


get/v1/projects/{projectId}/whatsapp/senders/{senderId}/activities
Request samples 
Response samples 
application/json
Response for all sender activities.



{
  • "totalSize": 2,
  • "pageSize": 50,
  • "notifications": [
    • {
      },
    • {
      }
    ]
}
Delete pending or rejected changes to a sender GA 
Delete pending or rejected changes to a sender.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Responses 
204
Sender changes deleted


400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


500
InternalServerError


delete/v1/projects/{projectId}/whatsapp/senders/{senderId}/changes
Request samples 
Response samples 
application/json
{
  • "errorCode": "project_not_initialized",
  • "message": "Project not initialized for WhatsApp.",
  • "resolution": "Verify that the project ID is correct and that it has been onboarded for WhatsApp."
}
Creates a comment for a sender in project GA 
Creates a comment for a sender in project.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Request Body schema: application/json
required
Comment data


comment
required
string  [ 1 .. 65535 ] characters 
 
Responses 
201
Created comment for a sender in project


Response Schema: application/json
type
required
string
 Value: "CREATED"  
comment
required
string
 
created
string
 
400
BadRequest


401
Unauthorized


404
NotFound


500
InternalServerError


post/v1/projects/{projectId}/whatsapp/senders/{senderId}/comments
Request samples 
application/json
  Example body request to create a comment.
  



{
  • "comment": "Example comment."
}
Response samples 
application/json
Response when successfully creating a comment.



{
  • "type": "CREATED",
  • "comment": "Example comment",
  • "created": "2023-01-19T13:11:08.204Z"
}
Register sender for project GA 
Triggers sender registration with the requested method. An OTP code will be sent over the requested method that will need to be used in the Verify sender endpoint.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Request Body schema: application/json
required
Sender register data


method
required
string
Registration Method of the sender.


 Enum: "SMS" "VOICE"  
Responses 
200
Response Schema: application/json
id
required
string
The unique ID of the sender.


 
method
required
string
Registration Method of the sender.


 Enum: "SMS" "VOICE" "UNRECOGNIZED"  
accepted
required
string
The UTC Date Time in ISO 8601 for when the sender was accepted.


 
400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


429
TooManyRequests


500
InternalServerError


post/v1/projects/{projectId}/whatsapp/senders/{senderId}/register
Request samples 
application/json
  Example body request to register.
  



{
  • "method": "SMS"
}
Response samples 
application/json
Response when successfully register a sender.



{
  • "id": "cf11794a-6a5e-4a12-b103-da79bd378bf1",
  • "method": "SMS",
  • "accepted": "2023-01-19T13:11:08.204Z"
}
Verify sender for project GA 
Verify sender with the OTP received after triggering registration.



SecurityBasic or OAuth2.0 
Request 
path Parameters
projectId
required
string
The unique ID of the project. You can find this on the Sinch Dashboard.


 
senderId
required
string
The unique ID of the sender.


 
Request Body schema: application/json
required
Sender register data


code
required
string <otp> 
OTP code to verify the sender. Must be exact 6 characters without spaces.


 
Responses 
204
Sender verified


400
BadRequest


401
Unauthorized


404
NotFound


409
Conflict


500
InternalServerError


post/v1/projects/{projectId}/whatsapp/senders/{senderId}/verify
Request samples 
application/json
  Example body request to verify.
  



{
  • "code": "123456"
}
Response samples 
application/json
{
  • "errorCode": "invalid_input",
  • "message": "Invalid input.",
  • "resolution": "Correct the validation errors and submit again.",
  • "additionalInformation": {
    • "validationErrors": [
      ]
    }
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2025 Sinch. All rights reserved.