Send Text Message
Send a WhatsApp text message to any mobile number.
Text vs Template Message
GET / POST
https://app.botbee.io/api/v1/whatsapp/send
Within the 24-hour customer-service window you may send a free-form text message. Outside that window use a pre-approved template message instead.
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
message
String
Required
Text message content
↳ URL-encode value for GET
phone_number
String
Required
Recipient phone number
↳ Numeric · starts with country code
Request Examples
https://app.botbee.io/api/v1/whatsapp/send?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&message=TEXT-MESSAGE&phone_number=PHONE-NUMBER
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/send' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'message=TEXT-MESSAGE' \
-d 'phone_number=PHONE-NUMBER'
Sample Responses
200 OK
{
"status": "1",
"wa_message_id": "wamid.HBgNODgwMTcyMzMwOTAwMxUCABEYEjlGQkY3MEFEMEVGODhCNDkxNQA=",
"message": "Message sent successfully."
}
Subscriber limit
{"status":"0","message":"Subscriber limit has been exceeded. You cannot have more subscribers."}
Send Interactive Buttons
Send a session message with 1–3 WhatsApp reply buttons, with optional image / video / document header.
Reply buttons are session messages — send within the 24-hour customer-service window.
POST
https://app.botbee.io/api/v1/whatsapp/send/interactive-buttons
Send 1 to 3 buttons; each title can be up to 20 characters. To attach media, supply
media_url (or media_id) — allowed header types are image, video, document only (audio is not supported as a header).
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Recipient phone number
↳ Numeric · starts with country code
message
String
Required
Message body shown above the buttons
buttons
JSON Array
Required
1–3 reply buttons. Each item: string or object with id + title
↳ e.g. [{"id":"buy","title":"Buy Now"}]
button_header_text
String
Optional
Optional text header
↳ Ignored when a media header is sent
button_footer_text
String
Optional
Optional footer text
media_url
String
Optional
Public HTTPS URL — image, video, or document for interactive header
↳ Use either media_url or media_id
media_id
String
Optional
WhatsApp media ID from the Upload Media API
↳ Requires media_type when used
media_type
String
Conditional
One of: image · video · document
↳ Required when using media_id or media_url without extension
media_name
String
Optional
Filename to display for document headers
↳ Only used when media_type is document
Request Examples
curl -X POST "https://app.botbee.io/api/v1/whatsapp/send/interactive-buttons" \
-H "Accept: application/json" \
-d "apiToken=API-KEY" \
-d "phone_number_id=PHONE-NUMBER-ID" \
-d "phone_number=PHONE-NUMBER" \
-d "message=Would you like to continue?" \
-d 'buttons=[{"id":"buy_now","title":"Buy Now"},{"id":"details","title":"View Details"}]' \
-d "button_header_text=Product update" \
-d "button_footer_text=Tap an option"
curl -X POST "https://app.botbee.io/api/v1/whatsapp/send/interactive-buttons" \
-H "Accept: application/json" \
-d "apiToken=API-KEY" \
-d "phone_number_id=PHONE-NUMBER-ID" \
-d "phone_number=PHONE-NUMBER" \
-d "message=Check this product and choose an action." \
-d "media_url=https://example.com/product.jpg" \
-d "media_type=image" \
-d 'buttons=[{"id":"buy_now","title":"Buy Now"},{"id":"details","title":"View Details"}]' \
-d "button_footer_text=Tap an option"
Sample Responses
200 OK
{
"status": "1",
"wa_message_id": "wamid.HBgNODgwMTcyMzMwOTAwMxUCABEYEjlGQkY3MEFEMEVGODhCNDkxNQA=",
"message": "Message sent successfully."
}
Invalid button count
{"status":"0","message":"You can send between 1 and 3 reply buttons."}
Invalid media type
{"status":"0","message":"When sending media with buttons, media_type must be one of: image, video, document."}
Send Media
Send an image, video, audio, or document to a WhatsApp number.
GET / POST
https://app.botbee.io/api/v1/whatsapp/send/file
Provide media_url or media_id — at least one is required.
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Recipient phone number
↳ Numeric · starts with country code
media_url
String
Conditional
Public HTTPS URL of the file. WhatsApp downloads from this link.
↳ Required if no media_id
media_id
String
Conditional
WhatsApp media ID from the Upload Media API
↳ Required if no media_url
media_type
String
Conditional
One of: image · video · audio · document
↳ Required with media_id or extensionless URL
media_caption_text
String
Optional
Caption for image, video, or document
↳ Not available for audio
Request Examples
https://app.botbee.io/api/v1/whatsapp/send/file?apiToken=API-KEY&phone_number_id=PHONE-ID&phone_number=PHONE&media_type=image&media_url=https://example.com/image.jpg
https://app.botbee.io/api/v1/whatsapp/send/file?apiToken=API-KEY&phone_number_id=PHONE-ID&phone_number=PHONE&media_type=image&media_id=MEDIA_ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/send/file' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'media_url=https://example.com/file.jpg' \
-d 'media_type=image' \
-d 'media_caption_text=Optional caption'
Sample Responses
200 OK
{
"status": "1",
"wa_message_id": "wamid.HBgNODgwMTcyMzMwOTAwMxUCABEYEjlGQkY3MEFEMEVGODhCNDkxNQA=",
"message": "Message sent successfully."
}
Subscriber limit
{"status":"0","message":"Subscriber limit has been exceeded. You cannot have more subscribers."}
Upload Media
Upload a file to receive a media_id for use with Send Media or Interactive Buttons.
POST (multipart)
https://app.botbee.io/api/v1/whatsapp/upload/media
Endpoint uses multipart/form-data. Pass your API key as
apiToken field or as Authorization: Bearer header.
Parameters
apiToken
String
Required
Your API key
↳ Or: Authorization: Bearer token
phone_number_id
String
Required
WhatsApp account phone number ID
media_file
File
Required
Supported: image · video · audio · document
↳ Field name must be media_file
Request Examples
curl -X POST "https://app.botbee.io/api/v1/whatsapp/upload/media" \
-H "Authorization: Bearer API-KEY" \
-H "Accept: application/json" \
-F "phone_number_id=PHONE-NUMBER-ID" \
-F "media_file=@/path/to/file.jpg"
Sample Responses
200 OK
{
"status": "1",
"media_id": "1739230482390482",
"media_type": "image",
"message": "Upload successful. Use media_id and media_type with the Send File API."
}
Error
{"status":"0","message":"..."}
Get Conversation
Retrieve the message history for a specific subscriber.
GET / POST
https://app.botbee.io/api/v1/whatsapp/get/conversation
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
limit
Number
Required
Number of messages to return
offset
Number
Optional
Pagination offset
Request Examples
https://app.botbee.io/api/v1/whatsapp/get/conversation?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER&limit=10&offset=1
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/get/conversation' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'limit=10' \
-d 'offset=1'
Sample Responses
200 OK
{
"status": "1",
"message": [
{
"id": 8003,
"sender": "bot",
"agent_name": null,
"wa_message_id": "wamid.HBgNODgwMTcy...",
"conversation_time": "2024-07-28 13:21:03",
"message_status": null,
"failed_reason": ""
}
]
}
Get PostBack List
Retrieve all post-back items configured for a WhatsApp bot.
GET / POST
https://app.botbee.io/api/v1/whatsapp/get/post-back-list
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
Request Examples
https://app.botbee.io/api/v1/whatsapp/get/post-back-list?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/get/post-back-list' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID'
Sample Responses
200 OK
{
"status": "1",
"message": [
{
"id": 671,
"postback_id": "QUICK_REPLY_LOCATION_REPLY_BOT",
"bot_name": "Location quick reply",
"visual_flow_type": "flow",
"postback_type": "main",
"updated_at": "2024-07-14 05:25:55"
}
]
}
Get Message Delivery Status
Check the delivery status of a previously sent WhatsApp message.
GET / POST
https://app.botbee.io/api/v1/whatsapp/get/message-status
Parameters
apiToken
String
Required
Your API key
wa_message_id
String
Required
WhatsApp message ID to check
whatsapp_bot_id
Number
Required
WhatsApp bot ID
Request Examples
https://app.botbee.io/api/v1/whatsapp/get/message-status?apiToken=API-KEY&wa_message_id=WAMID.XXXXX&whatsapp_bot_id=123
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/get/message-status' \
-d 'apiToken=API-KEY' \
-d 'wa_message_id=WAMID.XXXXX' \
-d 'whatsapp_bot_id=123'
Sample Responses
200 OK
{
"status": "1",
"message": {
"message_status": "delivered",
"delivery_status_updated_at": "2024-07-28 13:21:03",
"read_time": null,
"failed_time": null,
"failed_reason": ""
}
}
Get Bot Template
Retrieve approved WhatsApp message templates for an account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/template/list
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
Request Examples
https://app.botbee.io/api/v1/whatsapp/template/list?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/template/list' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID'
Sample Responses
200 OK
{
"status": "1",
"message": {
"id": 48,
"template_name": "ada",
"locale": "en_US",
"header_type": "media",
"status": "Rejected"
}
}
Trigger Bot Flow
Trigger a bot flow for a specific subscriber.
GET / POST
https://app.botbee.io/api/v1/whatsapp/trigger-bot
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
bot_flow_unique_id
String
Required
Bot Flow Unique ID
phone_number
String
Required
Target phone number
↳ Numeric · starts with country code
Request Examples
https://app.botbee.io/api/v1/whatsapp/trigger-bot?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&bot_flow_unique_id=BOT-FLOW-UNIQUE-ID&phone_number=PHONE-NUMBER
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/trigger-bot' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'bot_flow_unique_id=BOT-FLOW-UNIQUE-ID' \
-d 'phone_number=PHONE-NUMBER'
Sample Responses
200 OK
{"status":"1","message":"Bot has been trigger successfully."}
Get Subscriber
Look up a subscriber by their WhatsApp phone number.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/get
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Subscriber phone number
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/get?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/get' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER'
Sample Responses
200 OK
{
"status": "1",
"message": [{
"subscriber_id": 144,
"chat_id": "0123456789",
"first_name": "John",
"last_name": "Doe",
"email": "test@gmail.com",
"gender": "Male",
"created_at": "2026-04-07 10:30:00",
"assigned_agent_id": 12,
"assigned_agent": "Support Agent",
"bot_reply_label": "Bot Reply On",
"ai_reply_label": "AI Reply On",
"label_names": "Label1,Label2"
}]
}
Subscribers List
Paginated list of all subscribers for a WhatsApp account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/list
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
limit
Number
Required
Number of subscribers to return
offset
Number
Optional
Pagination offset
orderBy
Number
Optional
Sort order
↳ 1 = latest message first · 0 = default
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/list?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&limit=10&offset=1&orderBy=0
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/list' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'limit=10' \
-d 'offset=1' \
-d 'orderBy=0'
Sample Responses
200 OK
{
"status": "1",
"message": [
{ "subscriber_id": 144, "chat_id": "0123456789", "first_name": "John", "last_name": "Doe", "label_names": "One,Two" },
{ "subscriber_id": 157, "chat_id": "0198765432", "first_name": "Jane", "last_name": "Smith", "label_names": "Three" }
]
}
Create Subscriber
Add a new subscriber / contact to a WhatsApp account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/create
Parameters
apiToken
String
Required
Your API key
phoneNumberID
String
Required
WhatsApp account phone number ID
name
String
Required
Subscriber display name
phoneNumber
String
Required
Subscriber phone number
↳ Country code included · no + sign
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/create?apiToken=API-KEY&phoneNumberID=PHONE-NUMBER-ID&name=NAME&phoneNumber=MOBILE
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/create' \
-d 'apiToken=API-KEY' \
-d 'phoneNumberID=PHONE-NUMBER-ID' \
-d 'name=NAME' \
-d 'phoneNumber=MOBILE'
Sample Responses
200 OK
{"status":"1","mesasge":"WhatsApp subscriber has been created."}
Account not found
{"status":"0","message":"WhatsApp account not found."}
Subscriber limit
{"status":"0","message":"Subscriber limit has been exceeded. You cannot have more subscribers."}
Already exists
{"status":"0","message":"Something went wrong or subscriber already exist."}
Update Subscriber
Update profile details for an existing subscriber.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/update
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Subscriber phone number
first_name
String
Optional
First name
last_name
String
Optional
Last name
gender
String
Optional
Gender
label_ids
String
Optional
Label IDs to assign
↳ Comma-separated · e.g. 1,4,5
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/update?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER&first_name=FIRST-NAME&last_name=LAST-NAME
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/update' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'first_name=FIRST-NAME' \
-d 'last_name=LAST-NAME' \
-d 'gender=GENDER' \
-d 'label_ids=1,4,5'
Sample Responses
200 OK
{"status":"1","message":"Subscriber Updated Successfully."}
Delete Subscriber
Permanently remove a subscriber from a WhatsApp account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/delete
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Subscriber phone number
↳ Numeric · starts with country code
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/delete?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/delete' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER'
Sample Responses
200 OK
{"status":"1","message":"Subscriber has been deleted successfully."}
Reset User Input Flow
Reset the bot flow state for a subscriber.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/reset/user-input-flow
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
WhatsApp account phone number ID
phone_number
String
Required
Subscriber phone number
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/reset/user-input-flow?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/reset/user-input-flow' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER'
Sample Responses
200 OK
{"status":"1","message":"Reset User Input Flow successfully."}
Assign Chat to Team Member
Route a subscriber's live chat to a specific team member.
GET / POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-to-team-member
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
team_member_id
Integer
Required
Team member ID to assign
Request Examples
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-to-team-member?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&phone_number=PHONE-NUMBER&team_member_id=TEAM-MEMBER-ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-to-team-member' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'team_member_id=TEAM-MEMBER-ID'
Sample Responses
200 OK
{"status":"1","message":"Successfully Assign Agent to Conversation."}
Assign Custom Fields
Set custom field values on a subscriber profile.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-custom-fields
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
custom_fields
JSON
Required
Custom field names and values as a JSON object
↳ {"field_name": "value", …}
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-custom-fields' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'custom_fields={"field_name1":"value1","field_name2":"value2"}'
Sample Responses
200 OK
{"status":"1","message":"Subscriber changes have been saved successfully."}
Custom Fields List
Retrieve all custom fields configured for your account.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/custom-fields/list
Parameters
apiToken
String
Required
Your API key
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/custom-fields/list' \
-d 'apiToken=API-KEY'
Sample Responses
200 OK
{
"status": "1",
"message": "Custom fields retrieved successfully",
"data": [
{ "id": 1, "name": "customer_name", "reply_type": "text" },
{ "id": 2, "name": "customer_email", "reply_type": "email" }
]
}
Assign Labels
Add one or more labels to a subscriber.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-labels
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
label_ids
String
Required
Label IDs to assign
↳ Comma-separated · e.g. 1,4,5
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-labels' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'label_ids=1,4,5'
Sample Responses
200 OK
{"status":"1","message":"Labels have been assigned successfully."}
Remove Labels
Remove labels from a subscriber.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/remove-labels
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
label_ids
String
Required
Label IDs to remove
↳ Comma-separated · e.g. 1,4,5
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/remove-labels' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'label_ids=1,4,5'
Sample Responses
200 OK
{"status":"1","message":"Labels have been removed successfully."}
Assign Sequence
Enrol a subscriber in one or more drip sequences.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-sequence
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
sequence_ids
String
Required
Sequence IDs to assign
↳ Comma-separated · e.g. 1,4,5
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/assign-sequence' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'sequence_ids=1,4,5'
Sample Responses
200 OK
{"status":"1","message":"Sequences have been assigned successfully."}
Remove Sequence
Remove a subscriber from one or more drip sequences.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/remove-sequence
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
sequence_ids
String
Required
Sequence IDs to remove
↳ Comma-separated · e.g. 1,4,5
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/remove-sequence' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'sequence_ids=1,4,5'
Sample Responses
200 OK
{"status":"1","message":"Sequences have been removed successfully."}
Add Notes to Subscriber
Attach an internal note to a subscriber's chat.
POST
https://app.botbee.io/api/v1/whatsapp/subscriber/chat/add-notes
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
phone_number
String
Required
Subscriber phone number
note_text
String
Required
Note content
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/subscriber/chat/add-notes' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'phone_number=PHONE-NUMBER' \
-d 'note_text=NOTE-TEXT'
Sample Responses
200 OK
{"status":"1","message":"Notes have been added successfully."}
Label List
Return all labels for a WhatsApp account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/label/list
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
Request Examples
https://app.botbee.io/api/v1/whatsapp/label/list?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/label/list' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID'
Sample Responses
200 OK
{"status":"1","message":[{"id":1,"label_name":"Your label name","status":"1"}]}
Label Create
Create a new label for a WhatsApp account.
GET / POST
https://app.botbee.io/api/v1/whatsapp/label/create
Parameters
apiToken
String
Required
Your API key
phone_number_id
String
Required
Your WhatsApp phone number ID
label_name
String
Required
Label name
Request Examples
https://app.botbee.io/api/v1/whatsapp/label/create?apiToken=API-KEY&phone_number_id=PHONE-NUMBER-ID&label_name=LABEL-NAME
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/label/create' \
-d 'apiToken=API-KEY' \
-d 'phone_number_id=PHONE-NUMBER-ID' \
-d 'label_name=LABEL-NAME'
Sample Responses
200 OK
{"status":"1","message":"Label has been created successfully."}
Catalog List
List all connected WhatsApp catalogs.
GET / POST
https://app.botbee.io/api/v1/whatsapp/catalog/list
Parameters
apiToken
String
Required
Your API key
Request Examples
https://app.botbee.io/api/v1/whatsapp/catalog/list?apiToken=API-KEY
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/catalog/list' \
-d 'apiToken=API-KEY'
Sample Responses
200 OK
{
"status": true,
"message": [{
"catalog_id": "1429267xxxx5095",
"catalog_name": "The White",
"catalog_url": "https://xxxxx",
"checkout_settings": { "tax_percentage": "5.5", "shipping_charge": "20" }
}]
}
Sync Catalog
Sync products from a WhatsApp catalog into BotBee.
POST
https://app.botbee.io/api/v1/whatsapp/catalog/sync
Parameters
apiToken
String
Required
Your API key
whatsapp_catalog_id
String
Required
WhatsApp catalog ID to sync
Request Examples
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/catalog/sync' \
-d 'apiToken=API-KEY' \
-d 'whatsapp_catalog_id=WHATSAPP-CATALOG-ID'
Sample Responses
200 OK
{"status":"1","message":"Catalog products have been synced successfully."}
Catalog Order List
Retrieve orders placed through a WhatsApp catalog.
GET / POST
https://app.botbee.io/api/v1/whatsapp/catalog/order/list
Parameters
apiToken
String
Required
Your API key
whatsapp_catalog_id
String
Optional
Filter by a specific catalog
Request Examples
https://app.botbee.io/api/v1/whatsapp/catalog/order/list?apiToken=API-KEY&whatsapp_catalog_id=WHATSAPP-CATALOG-ID
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/catalog/order/list' \
-d 'apiToken=API-KEY' \
-d 'whatsapp_catalog_id=WHATSAPP-CATALOG-ID'
Sample Responses
200 OK
{
"status": "1",
"message": [{
"order_unique_id": "172310467380123456789",
"catalog_name": "Catalog Name",
"first_name": "John",
"cart_total": 4300,
"cart_currency": "USD",
"cart_status_raw": "Submitted",
"payment_method": "Cash on Delivery",
"ordered_at": "2024-08-08 08:11:13"
}]
}
Catalog Order Status Change
Update the fulfillment status of a catalog order.
GET / POST
https://app.botbee.io/api/v1/whatsapp/catalog/order/status-change
Parameters
apiToken
String
Required
Your API key
order_unique_id
String
Required
Catalog order unique ID
cart_status
String
Required
New order status
↳ Approved · Completed · Shipped · Delivered · Refunded
Request Examples
https://app.botbee.io/api/v1/whatsapp/catalog/order/status-change?apiToken=API-KEY&order_unique_id=ORDER-UNIQUE-ID&cart_status=Shipped
curl -X POST 'https://app.botbee.io/api/v1/whatsapp/catalog/order/status-change' \
-d 'apiToken=API-KEY' \
-d 'order_unique_id=ORDER-UNIQUE-ID' \
-d 'cart_status=Shipped'
Sample Responses
200 OK
{"status":true,"message":"Cart status has been updated successfully"}
Get Direct Login URL
Generate a unique, secure one-time login URL for any user.
GET / POST
https://app.botbee.io/api/v1/user/get/direct-login-url
Parameters
apiToken
String
Required
Your API key
email
Email
Required
User email address
name
String
Optional
User full name
mobile
String
Optional
User phone number
package_id
Integer
Conditional
Package ID to assign
↳ Required for new users
expired_date
String
Conditional
Package expiry date
↳ Required for new users · YYYY-MM-DD
status
String
Optional
Account status
↳ 1 = active · 0 = inactive
create_on_fail
Boolean
Optional
Auto-create behaviour
↳ 1 = create if not found · 0 = return error
Request Examples
https://app.botbee.io/api/v1/user/get/direct-login-url?apiToken=API-KEY&email=EMAIL&name=NAME&mobile=MOBILE&package_id=PACKAGE-ID&expired_date=EXPIRED-DATE&status=1&create_on_fail=1
curl -X POST 'https://app.botbee.io/api/v1/user/get/direct-login-url' \
-d 'apiToken=API-KEY' \
-d 'email=EMAIL' \
-d 'name=NAME' \
-d 'mobile=MOBILE' \
-d 'package_id=PACKAGE-ID' \
-d 'expired_date=EXPIRED-DATE' \
-d 'status=1' \
-d 'create_on_fail=1'
Sample Responses
200 OK
{
"status": "1",
"message": {
"email": "user@domain.com",
"password": "xxxxxxxxxx",
"login_url": "https://app.botbee.io/login",
"direct_login_url": "https://app.botbee.io/direct-login/xxxxxxxxxx"
}
}
Login URL — New Users Only
Creates a new user and returns a one-time login URL. Returns an error if the email already exists.
GET / POST
https://app.botbee.io/api/v1/user/get/direct-login-url/only-new-users
This endpoint is new-user only. If the email already exists, the API returns
"User already existed" — no login URL is issued.
Parameters
apiToken
String
Required
Your API key
email
Email
Required
User email address
package_id
Integer
Required
Package ID to assign
expired_date
String
Required
Package expiry date
↳ Format YYYY-MM-DD
Request Examples
https://app.botbee.io/api/v1/user/get/direct-login-url/only-new-users?apiToken=API-KEY&email=EMAIL&package_id=PACKAGE-ID&expired_date=2026-12-31
curl -X POST 'https://app.botbee.io/api/v1/user/get/direct-login-url/only-new-users' \
-d 'apiToken=API-KEY' \
-d 'email=EMAIL' \
-d 'package_id=PACKAGE-ID' \
-d 'expired_date=2026-12-31'
Sample Responses
200 OK — user created
{
"status": "1",
"message": {
"email": "user@domain.com",
"password": "xxxxxxxxxx",
"login_url": "https://app.botbee.io/login",
"direct_login_url": "https://app.botbee.io/direct-login/xxxxxxxxxx"
}
}
409 — user already exists
{"status":"0","message":"User already existed"}