Send Message

Send a message to initiate a conversation with a contact

POST /api/v1/bot-integrations/{botIntegrationId}/messages/send

cURL

whatsapp

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": "[e-mail]",
  "firstName": "John",
  "lastName": "Doe",
  "timeZone": "America/New_York"
}
'

201

Example

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

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.

Authorizations

Authorization · string · header · required

Bearer token authentication using your API key

Path Parameters

botIntegrationId · integer · required

The ID of your bot integration

Body

application/json

phoneNumber · string · required

Contact's phone number in international format

Example:

"1234567890"

templateName · string

Name of the WhatsApp message template (WhatsApp only)

Example:

"hello_world"

language · string

Language code for the template (WhatsApp only)

Example:

"en_US"

bodyParameters · object[]

Parameters to fill template placeholders (WhatsApp only)

Show child attributes

message · string

The message text to send (SMS/Twilio only)

Example:

"Hello! I'm here to help you schedule an appointment."

email · string<email>

Contact's email address

Example:

"[e-mail]"

firstName · string

Contact's first name

Example:

"John"

lastName · string

Contact's last name

Example:

"Doe"

fullName · string

Contact's full name

Example:

"John Doe"

timeZone · string

Contact's timezone

Example:

"America/New_York"

metadata · object

Custom key-value pairs to store with the contact

Show child attributes

Example:

{
  "source": "website",
  "campaign": "summer2024"
}

calendarIntegrationId · integer

ID of calendar integration to use for this conversation

Example:

123

Response

201

application/json

Message sent successfully

The response is of type integer.

Example:

201