> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trysetter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send Message
> Send a message to initiate a conversation with a contact
## 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
The `botIntegrationId` 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. |
Because a bot can have both a WhatsApp and an SMS integration, each with its own Bot Integration ID, you use the Bot Integration ID — not the bot ID — to tell this endpoint which channel to send through.
Open your bot → **Integrations** → **WhatsApp** or **Twilio**, and copy the **Bot Integration ID** shown in the integration details.
## Platform Support
### WhatsApp
For WhatsApp integrations, you'll need to specify:
* `templateName` - The approved WhatsApp message template
* `language` - 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.
## OpenAPI
````yaml POST /api/v1/bot-integrations/{botIntegrationId}/messages/send
openapi: 3.0.3
info:
title: Setter AI API
description: API for Setter AI appointment booking assistant
version: 1.0.0
contact:
email: support@trysetter.com
servers:
- url: https://chat.trysetter.com
description: Production server
security:
- bearerAuth: []
paths:
/api/v1/bot-integrations/{botIntegrationId}/messages/send:
post:
tags:
- Messages
summary: Send Message
description: >-
Send a message to initiate a conversation with a contact. This endpoint
supports both WhatsApp and SMS platforms and automatically creates
contacts and conversations.
**Rate Limiting**: You cannot send another bot-initiated message to the
same phone number within 30 minutes.
operationId: sendMessage
parameters:
- name: botIntegrationId
in: path
required: true
schema:
type: integer
description: The ID of your bot integration
example: 123
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
examples:
whatsapp:
summary: WhatsApp Template Message
value:
phoneNumber: '1234567890'
templateName: appointment_booking
language: en_US
bodyParameters:
- type: text
text: John
parameter_name: customer_name
email: john@example.com
firstName: John
lastName: Doe
timeZone: America/New_York
sms:
summary: SMS Message
value:
phoneNumber: '1234567890'
message: >-
Hi! I'm your AI assistant. How can I help you schedule an
appointment today?
email: jane@example.com
firstName: Jane
lastName: Smith
timeZone: America/Los_Angeles
metadata:
source: website_form
page: /contact
responses:
'201':
description: Message sent successfully
content:
application/json:
schema:
type: integer
example: 201
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_phone:
summary: Missing phone number
value:
message: Missing phone number
missing_message:
summary: Missing message for SMS
value:
message: Bad Request - message is required
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: Forbidden
'429':
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: >-
Error: Bot initiated message was already sent in the last 30
minutes
'500':
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Internal server error occurred
components:
schemas:
SendMessageRequest:
type: object
properties:
phoneNumber:
type: string
description: Contact's phone number in international format
example: '1234567890'
templateName:
type: string
description: Name of the WhatsApp message template (WhatsApp only)
example: hello_world
language:
type: string
description: Language code for the template (WhatsApp only)
example: en_US
bodyParameters:
type: array
items:
$ref: '#/components/schemas/BodyParameter'
description: Parameters to fill template placeholders (WhatsApp only)
message:
type: string
description: The message text to send (SMS/Twilio only)
example: Hello! I'm here to help you schedule an appointment.
email:
type: string
format: email
description: Contact's email address
example: john@example.com
firstName:
type: string
description: Contact's first name
example: John
lastName:
type: string
description: Contact's last name
example: Doe
fullName:
type: string
description: Contact's full name
example: John Doe
timeZone:
type: string
description: Contact's timezone
example: America/New_York
metadata:
type: object
additionalProperties:
type: string
description: Custom key-value pairs to store with the contact
example:
source: website
campaign: summer2024
calendarIntegrationId:
type: integer
description: ID of calendar integration to use for this conversation
example: 123
required:
- phoneNumber
ErrorResponse:
type: object
properties:
message:
type: string
description: Error message
BodyParameter:
type: object
properties:
type:
type: string
enum:
- text
description: Type of parameter
text:
type: string
description: Text content for the parameter
parameter_name:
type: string
description: Optional parameter name for template placeholder
required:
- type
- text
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer token authentication using your API key
````