curl --request POST \
--url https://chat.trysetter.com/api/v1/bot-integrations/{botIntegrationId}/messages/send \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phoneNumber": "1234567890",
"templateName": "appointment_booking",
"language": "en_US",
"bodyParameters": [
{
"type": "text",
"text": "John",
"parameter_name": "customer_name"
}
],
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"timeZone": "America/New_York"
}
'
201
API Reference
Send Message
Send a message to initiate a conversation with a contact
POST
/
api
/
v1
/
bot-integrations
/
{botIntegrationId}
/
messages
/
send
curl --request POST \
--url https://chat.trysetter.com/api/v1/bot-integrations/{botIntegrationId}/messages/send \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"phoneNumber": "1234567890",
"templateName": "appointment_booking",
"language": "en_US",
"bodyParameters": [
{
"type": "text",
"text": "John",
"parameter_name": "customer_name"
}
],
"email": "[email protected]",
"firstName": "John",
"lastName": "Doe",
"timeZone": "America/New_York"
}
'
201
Overview
This endpoint allows you to send a message to initiate a conversation with a contact. It supports both WhatsApp and SMS platforms and automatically handles contact creation and conversation management.Rate Limiting: You cannot send another bot-initiated message to the same phone number within 30 minutes.
Bot Integration ID
ThebotIntegrationId in the URL path identifies which channel of which bot the message is sent through. It is not the same as the bot ID.
| Identifier | What it is | Where to find it |
|---|---|---|
| Bot ID | Identifies the bot itself. A single bot can run on multiple channels (WhatsApp, SMS, web chat). | In the dashboard URL when you open a bot, e.g. …/bots/700/… → bot ID is 700. |
| Bot Integration ID | Identifies one specific channel connection of a bot (e.g. that bot’s WhatsApp integration, or its SMS integration). Each channel has its own Bot Integration ID. | In the bot’s Integrations settings, open the WhatsApp or Twilio (SMS) integration. The Bot Integration ID is displayed as a read-only field at the top of the integration details. |
Open your bot → Integrations → WhatsApp or Twilio, and copy the Bot Integration ID shown in the integration details.
Platform Support
templateName- The approved WhatsApp message templatelanguage- Language code (e.g., “en_US”)bodyParameters- Parameters to fill template placeholders
SMS (Twilio)
For SMS integrations, you’ll need to specify:message- The text message to send
Important Notes
- Authentication: All requests require a Bearer token in the Authorization header
- Phone Format: Always use international format (e.g., 1234567890)
- Contact Management: Contacts are automatically created or updated
- Conversation Tracking: Conversations are automatically created and linked
- Calendar Integration: Optionally link conversations to specific calendar integrations
Getting Your API Key
API keys can be generated from your Setter AI dashboard under Settings > API Keys. Keep your API key secure and never expose it in client-side code.Authorizations
Bearer token authentication using your API key
Path Parameters
The ID of your bot integration
Body
application/json
Contact's phone number in international format
Example:
"1234567890"
Name of the WhatsApp message template (WhatsApp only)
Example:
"hello_world"
Language code for the template (WhatsApp only)
Example:
"en_US"
Parameters to fill template placeholders (WhatsApp only)
Show child attributes
Show child attributes
The message text to send (SMS/Twilio only)
Example:
"Hello! I'm here to help you schedule an appointment."
Contact's email address
Example:
Contact's first name
Example:
"John"
Contact's last name
Example:
"Doe"
Contact's full name
Example:
"John Doe"
Contact's timezone
Example:
"America/New_York"
Custom key-value pairs to store with the contact
Show child attributes
Show child attributes
Example:
{ "source": "website", "campaign": "summer2024" }
ID of calendar integration to use for this conversation
Example:
123
Response
Message sent successfully
The response is of type integer.
Example:
201