openapi: 3.0.0
info:
version: 1.8.0
title: Route Mobile WhatsApp Business API
description: |-
The Route Mobile WhatsApp Business API enables enterprises to programmatically send and receive WhatsApp messages at scale. Use these APIs to integrate WhatsApp messaging into your applications for notifications, customer engagement, commerce, and support.
## Getting Started
1. **Authenticate** — Call the [Login API](#tag/Authentication/operation/loginApi) to obtain a JWT token.
2. **Send Messages** — Use the [Send Messages API](#tag/Messaging/operation/sendMessages) to deliver template or session messages.
3. **Receive Callbacks** — Configure your webhook URL to receive [delivery reports and incoming messages](#tag/Webhooks).
## Key Concepts
- **Template Messages** — Pre-approved message templates for outbound notifications (marketing, utility, authentication).
- **Session Messages** — Free-form messages within a 24-hour customer service window.
- **Bulk Campaigns** — Send messages to thousands of recipients via file upload.
- **Catalog & Commerce** — Product catalogs, payments, and order management via WhatsApp.
## Authentication
All API endpoints (except Login) require a JWT bearer token in the `Authorization` header. Tokens are valid for **one hour** by default.
```
Authorization: <your-jwt-token>
```
## Rate Limits
API rate limits are governed by your account tier. Contact your account manager for details.
## Support
For API support, visit the [Route Mobile Developer Hub](https://developers.routemobile.com/) or reach out to [product-desk@routemobile.com](mailto:product-desk@routemobile.com).
contact:
name: Route Mobile Developer Support
url: https://developers.routemobile.com/
email: product-desk@routemobile.com
termsOfService: https://www.routemobile.com/terms-of-service/
license:
name: Proprietary
url: https://www.routemobile.com/terms-of-service/
x-logo:
url: https://www.routemobile.com/wp-content/uploads/2023/04/route-mobile-logo.svg
altText: Route Mobile
x-readme:
explorer-enabled: true
proxy-enabled: true
samples-enabled: true
servers:
- url: https://apis.rmlconnect.net
security:
- BearerAuth: []
tags:
- name: Authentication
description: Authenticate with the Route Mobile WhatsApp Business API to obtain a JWT token for subsequent
API calls.
- name: Account Management
description: Manage your WhatsApp Business profile settings, account details, and profile photo.
- name: Messaging
description: Send template messages (marketing, utility, authentication) and session messages (text,
media, interactive, payments, flows) to individual recipients.
- name: Bulk Campaigns
description: Upload files, create, start, pause, and resume bulk messaging campaigns to reach large
audiences.
- name: Catalog Management
description: Create, update, delete, and fetch product feeds and catalog details for WhatsApp Commerce.
- name: Reports
description: Generate, download, and query messaging reports including delivery stats, campaign metrics,
opt-in data, and template usage counts.
- name: Opt-in Management
description: Store and verify user opt-in and opt-out consent for WhatsApp messaging compliance.
- name: Webhooks
description: Receive real-time delivery reports, incoming messages, and interaction callbacks via your
configured webhook URL.
paths:
/wba/v2/upload:
post:
tags:
- Bulk Campaigns
summary: File Upload
description: The File Upload API sends multiple messages to users in a single upload.
operationId: fileUpload
parameters:
- name: source
in: query
description: The details of the source for uploading the file for a bulk campaign.
required: false
style: form
explode: true
schema:
type: string
example: UI
- name: debug
in: query
description: The parameter that enables or disables the debug mode. Set the default value of
"debug=True" to enable the debug mode. The system generates additional information and logs
to help resolving troubleshoot and debug issues with the bulk campaigns.
style: form
explode: true
schema:
enum:
- 'True'
- 'False'
example: 'True'
requestBody:
description: Upload a CSV or text file containing recipient phone numbers and message content
for a bulk campaign.
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/BulkUploadRequest'
examples:
Example:
value:
campaign_type: string
file: string
file_mimetype: string
filename: string
message: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BulkUploadResponse'
examples:
Example 1:
value:
message: File uploaded successfully
campaign_id: 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx
file_type: text/csv
file_size: 19.0B
total_records: 1
valid_records: 1
duplicate records: 0
campaign_type: generalized
message_preview:
phone: '{phone}'
enable_acculync: true
extra: '{''asd'':''asd''}'
media:
type: media_template
template_name: boarding_pass_update
lang_code: en
header:
- image:
link: https://media.istockphoto.com/vectors/airplane-ticket-boarding-pass-ticket-template-vector-id878xxxxxx
body:
- text: Here is your boarding pass
asynchronous: false
country_code: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/JwtExpiredError'
examples:
JWT Token Expired:
value:
message: unable to process campaign request
reason: jwt token expired
status: failure
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'422':
description: Unprocessable Entity (WebDAV)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnknownCampaignTypeError'
- $ref: '#/components/schemas/FileMimetypeError'
examples:
Unknown campaign type:
value:
message: please check API docs for more info
status: failed
reason:
campaign_type:
- 'Must be one of: generalized, personalized.'
File Mimetype error:
value:
message: please check API docs for more info
status: failed
reason:
file_mimetype:
- 'Must be one of: text/csv, text/plain, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet,
application/vnd.openxmlformats-officedocument.spreadsheetml.template, application/vnd.ms-excel.sheet.macroEnabled.12,
application/vnd.ms-excel.template.macroEnabled.12, application/vnd.ms-excel.addin.macroEnabled.12,
application/vnd.ms-excel.sheet.binary.macroEnabled.12.'
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the message delivery.
message:
type: string
description: The message response.
examples:
Internal server error:
value:
status: failure
message: unable to process request
security:
- BearerAuth: []
/wba/v2/manage_campaign:
post:
tags:
- Bulk Campaigns
summary: Send Bulk Campaign
description: The Send Bulk Campaign API sends messages in bulk to multiple users, manages large-scale
campaigns, and reduces the workload for marketers or business owners.
operationId: sendBulkCampaign
parameters:
- name: debug
in: query
description: The parameter that enables or disables the debug mode. Set the default value of
"debug=True" to enable the debug mode. The system generates additional information and logs
to help resolving troubleshoot and debug issues with the bulk campaigns.
style: form
explode: true
schema:
enum:
- 'True'
- 'False'
example: 'True'
- name: source
in: query
description: The details of the source for uploading the file for a bulk campaign.
required: false
style: form
explode: true
schema:
type: string
example: UI
requestBody:
description: Start, pause, or resume a bulk messaging campaign.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/StartCampaignRequest'
- $ref: '#/components/schemas/ResumeCampaignRequest'
- $ref: '#/components/schemas/PauseCampaignRequest'
examples:
Start Campaign:
value:
campaign_action: start
campaign_id: '{campaign id}'
campaign_name: '{campaign name}'
file_mimetype: text/plain or text/csv
filename: '{filename with extension}'
payload:
type: '{payload type}'
scheduled_time: '{date and time in UTC e.g.2021-12-08 13:36:00}'
Pause Campaign:
value:
campaign_action: pause
campaign_id: '{campaign id}'
Resume Campaign:
value:
campaign_action: resume
campaign_id: '{campaign id}'
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignAcceptedResponse'
examples:
Example:
value:
status: success
message: campaign with id 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx is now processing
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignBadRequestError'
examples:
Filename Mismatch:
value:
status: failed
message: unable to process request
reason: file name mismatch between /upload and /campaign endpoints for 670b3fd4-d442-11ed-a821-xxxxxxxxxxxx
'401':
description: Authentication Failure
content:
application/json:
schema:
$ref: '#/components/schemas/CampaignAuthError'
examples:
JWT Token Expired:
value:
status: failed
message: unable to process request
reason: jwt token expired
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'422':
description: Unprocessable Entity (WebDAV)
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/IncorrectPayloadTypeError'
- $ref: '#/components/schemas/IncorrectCampaignIdError'
examples:
Incorrect Payload Type:
value:
message: please check API docs for more info
status: failed
reason:
payload:
- Unable to check payload type
Incorrect Campaign ID:
value:
message: please check API docs for more info
status: failed
reason:
campaign_id:
- Not a Valid Campaign Id
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the bulk campaign.
message:
type: string
description: The response message.
reason:
type: string
description: The reason for not processing the request.
examples:
Example:
value:
status: failed
message: unable to process request
reason: <internal server error reason>
security:
- BearerAuth: []
/wba/catalog/manager/v1/upload:
post:
tags:
- Catalog Management
summary: Upload File
description: Upload the product feed file.
operationId: uploadFile
requestBody:
description: Upload a product catalog file (CSV) with item details.
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CatalogUploadRequest'
examples:
Example 1:
value:
action: Update
file: string
file_name: file_name
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the upload file.
file_url:
type: string
description: The URL for uploading a file.
count:
type: integer
description: The number of products added in the catalog file.
examples:
Example:
value:
status: success
file_url: AWS S3 url
count: 20
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: array
description: The error received during file upload.
items:
type: string
examples:
Example:
value:
error:
- Provide file_name
'401':
description: Authentication Failure
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogUnauthorizedError'
examples:
JWT Token Expired:
value:
message: unable to process campaign request
reason: jwt token expired
status: failure
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the message delivery.
message:
type: string
description: The message response.
reason:
type: string
description: The reason for not processing the file upload request.
examples:
Example:
value:
status: failed
message: unable to process request
reason: reason
security:
- BearerAuth: []
/wba/catalog/manager/v1/create_product_feed:
post:
tags:
- Catalog Management
summary: Create Product Feed
description: Create a feed of products for a WhatsApp Business account.
operationId: createProductFeed
requestBody:
description: Create a new product feed with a file URL and optional schedule.
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/CreateProductFeedRequest'
examples:
Example 1:
value:
file_url: file_url
name: product_feed_name
schedule: '"interval":"HOURLY","scheduled_time":"2022-09-06 11:38:00"'
responses:
'200':
description: SUCCESS
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the create product feed.
examples:
Example:
value:
status: processing
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
name:
type: array
description: The required fields name.
items:
type: string
examples:
Example:
value:
name:
- Missing data for required field.
application/xml:
schema:
type: object
multipart/form-data:
schema:
type: object
'401':
description: Authentication Failure
content:
application/json:
schema:
$ref: '#/components/schemas/JwtExpiredError'
examples:
Incorrect authorization token:
value:
message: Unable to process request
status: Failed
reason: Please check the integrity or validity of the token sent.
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the message delivery.
message:
type: string
description: The message response.
reason:
type: string
description: The reason for not processing the product feed request.
examples:
Example:
value:
status: failed
message: unable to process request
reason: reason
security:
- BearerAuth: []
/wba/catalog/manager/v1/update_product_feed:
post:
tags:
- Catalog Management
summary: Update Product Feed
description: Update an existing feed of products for a WhatsApp Business account.
operationId: updateProductFeed
requestBody:
description: Update an existing product feed with new file content or schedule.
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/UpdateProductFeedRequest'
examples:
Example 1:
value:
file_url: string
product_feed_id: string
schedule: '"interval":"HOURLY","scheduled_time":"2022-09-06 11:38:00"'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the product feed.
examples:
Example:
value:
status: processing
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
product_feed_id:
type: array
description: The unique identifier of the product feed.
items:
type: string
examples:
Example:
value:
product_feed_id:
- Missing data for required field.
'401':
description: Authentication Failure
content:
application/json:
schema:
$ref: '#/components/schemas/JwtExpiredError'
examples:
Example:
value:
message: Unable to process request
status: Failed
reason: Please check the integrity or validity of the token sent.
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of product feed updates.
message:
type: string
description: The message response.
reason:
type: string
description: The reason for not updating the product feed.
examples:
Example:
value:
status: failed
message: unable to process request
reason: reason
security:
- BearerAuth: []
/wba/catalog/manager/v1/delete_product_feed:
post:
tags:
- Catalog Management
summary: Delete product Feed
description: Delete an existing feed of products for a WhatsApp Business account.
operationId: deleteProductFeed
requestBody:
description: Delete a product feed by its unique identifier.
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteProductFeedRequest'
application/xml:
schema:
$ref: '#/components/schemas/DeleteProductFeedRequestAlt'
examples:
Example 1:
value:
product_feed_id: '{product_feed_id}'
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status of the product feed.
examples:
Example 1:
value:
status: processing
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
product_feed_id:
type: array
description: The unique identifier of the product feed.
items:
type: string
examples:
Example 1:
value:
product_feed_id:
- Missing data for required field.
'401':
description: Authentication Failure
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogAuthError'
examples:
Example 1:
value:
message: Unable to process request
status: Failed
reason: Please check the integrity or validity of the token sent.
'404':
description: Page Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
examples:
Incorrect API URL:
value:
message: The requested URL was not found on the server. If you entered the URL manually
please check your spelling and try again.
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: The status for the product feed.
message:
type: string
description: The response message.
reason:
type: string
description: The reason for not deleting the product feed request.
examples:
Example 1:
value:
status: failed
message: unable to process request
reason: reason
security:
- BearerAuth: []
/wba/catalog/manager/v1/fetch_product_feed:
get:
tags:
- Catalog Management
summary: Fetch Product Feed Details
description: |-
Fetch product feed details, which is used to retrieve details about a specific product feed. The product feed includes a comma-separated list of field names:
- retailer_id: The ID of the retailer associated with the product.
- name: The name of the product.
- price: The price of the product.
- availability: The availability status of the product.
- id: The ID of the product.
- description: The description of the product.
- color: The color of the product.
- size: The size of the product.
- condition: The condition of the product.
- product_type: The type of product.
- quantity_to_sell_on_facebook: The quantity of the product to be sold on Facebook.
- url: The URL of the product.
- gender: The gender for which the product is intended.
- age_group: The age group for which the product is intended.
- sale_price: The sale price of the product.
- mpn: The manufacturer part number of the product.
- sale_price_effective_date: The effective date range of the sale price.
- brand: The brand of the product.
- custom_label_0: A custom label for the product.
operationId: fetchProductFeedDetails
parameters:
- name: product_feed_id
in: query
description: The unique ID of the product feed for which details should be fetched.
required: true
schema:
type: string
- name: fields
in: query
description: The fields that should be included in the response. The value should be a comma-separated
list of field names, such as "retailer_id, name, price, id".
required: true
schema:
type: string
- name: limit
in: query
description: The maximum number of products to return in the response. The value should be an
integer.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: array
description: The product feed details.
items:
type: object
examples:
Example 1:
value:
data:
- name: Dairy Milk Silk
id: xxxxxxxxxxxxxxxxx
price: ₹125.00
description: Dairy Products
retailer_id: xxxxx
- name: Maggie Pasta
id: xxxxxxxxxxxxxxxxx
price: ₹25.00
description: Instant Food
retailer_id: xxxxx
- name: Pulses 1kg
id: xxxxxxxxxxxxxxxxx
price: ₹200.00
description: Pulses are very good for health
retailer_id: xxxxx
- name: Cow Ghee
id: xxxxxxxxxxxxxxxxx
price: ₹499.00
description: Healty Cow Ghee
retailer_id: xxxxx
- name: BESAN 250 Gm
id: xxxxxxxxxxxxxxxxx
price: ₹32.00
description: Besan or Gram flour is made from Chana Dal. Besan atta is used too
make Bhaji, Vada , Sev, Chaklis, and many more items. It has various beauty benefits.
retailer_id: xxxxx
- name: Pastry
id: xxxxxxxxxxxxxxxxx
price: ₹50.00
description: Dairy Product
# --- truncated at 32 KB (456 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/route-mobile/refs/heads/main/openapi/route-mobile-whatsapp-business.yml