Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

Titan exposes one endpoint for all outbound WhatsApp messages: POST /api/messages/send. You pass a session name, a chatId, a message type, and the type-specific payload. Every message type — text, image, video, audio, document, sticker, poll, location, and contact — goes through the same route.

​
Required fields

​
session
string
required
The name of the WhatsApp session to send from (e.g. "default").
​
chatId
string
required
The recipient’s JID. Use {phone}@s.whatsapp.net for individuals (e.g. [email protected]), a group ID like [email protected] for groups, or status@broadcast to post to your WhatsApp Status.
​
type
string
required
The message type. One of: text, image, video, voice, file, poll, location, contact.

​
Message types

​
Text

​
text
string
required
The message body.
​
linkPreview
boolean
Set to true to generate a link preview when the text contains a URL.

​
Image

​
url
string
HTTPS URL of the image (JPEG, PNG, or WebP). Max 50 MB.
​
base64
string
Base64-encoded image bytes. Max 70 MB.
​
caption
string
Optional caption displayed below the image.

​
Video

​
url
string
HTTPS URL of the MP4 video. Max 50 MB.
​
base64
string
Base64-encoded video bytes. Max 70 MB.
​
caption
string
Optional caption displayed below the video.

​
Audio / voice note

​
url
string
HTTPS URL of the OGG or MP3 audio file. Max 50 MB.
​
base64
string
Base64-encoded audio bytes. Max 70 MB.
​
ptt
boolean
Set to true to deliver the audio as a push-to-talk voice note rather than a regular audio attachment.

​
Document

​
url
string
HTTPS URL of the file to send. Max 50 MB.
​
base64
string
Base64-encoded file bytes. Max 70 MB.
​
filename
string
required
The filename shown to the recipient (e.g. "report.pdf").
​
caption
string
Optional caption displayed below the file attachment.

​
Sticker

​
url
string
HTTPS URL of a WebP sticker. Max 50 MB.
​
base64
string
Base64-encoded WebP bytes. Max 70 MB.

​
Poll

​
pollTitle
string
required
The poll question.
​
pollOptions
string[]
required
The answer choices. Provide between 2 and 12 strings.
​
pollMultiSelect
boolean
Set to true to allow recipients to pick more than one option.

​
Location

​
latitude
number
required
Latitude in decimal degrees (e.g. 37.7749).
​
longitude
number
required
Longitude in decimal degrees (e.g. -122.4194).
​
address
string
Human-readable address shown below the pin (e.g. "San Francisco, CA").

​
Contact

​
vcard
string
required
A vCard 3.0 formatted string representing the contact to share.

​
Optional features

​
quotedMessage
object
Quote an existing message to create a threaded reply.
​
mentions
string[]
Array of JIDs to mention in the message (e.g. ["[email protected]"]). Up to 256 per message. Use in group messages to tag participants.
​
isForwarded
boolean
Mark the message as forwarded.

​
Send a text message

curl -X POST https://api.titan.io/api/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "default",
    "chatId": "[email protected]",
    "type": "text",
    "text": "Hello from Titan!"
  }'

​
Send an image message

curl -X POST https://api.titan.io/api/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "default",
    "chatId": "[email protected]",
    "type": "image",
    "url": "https://example.com/photo.jpg",
    "caption": "Check this out!"
  }'

​
Send a poll

curl -X POST https://api.titan.io/api/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "default",
    "chatId": "[email protected]",
    "type": "poll",
    "pollTitle": "When should we meet?",
    "pollOptions": ["Monday", "Tuesday", "Wednesday"],
    "pollMultiSelect": false
  }'

​
Response

A successful send returns HTTP 200 with the message details wrapped in a data object.
​
data
object

​
Post to WhatsApp Status

To post a message to your WhatsApp Status (visible to your contacts), set chatId to status@broadcast. Any message type supported for regular chats works for status posts. 
curl -X POST https://api.titan.io/api/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "default",
    "chatId": "status@broadcast",
    "type": "text",
    "text": "Good morning! 🌅"
  }'

​
Edit a sent message

You can update the text of a message you already sent. Only the text content can be changed. 
curl -X POST https://api.titan.io/api/sessions/default/messages/ABCDEF123456/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Updated message text"}'

​
Delete a message

Delete a message for everyone in the conversation. 
curl -X DELETE https://api.titan.io/api/sessions/default/messages/ABCDEF123456 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
React to a message

Send an emoji reaction to any message. Pass an empty string for reaction to remove an existing reaction. 
curl -X POST https://api.titan.io/api/sessions/default/messages/react \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "messageId": "ABCDEF123456",
    "reaction": "👍"
  }'

​
Typing indicators

Send a typing or recording indicator to a chat before delivering a message. This is handled automatically when Safe Mode is enabled, but you can also trigger it manually.
​
chatId
string
required
The chat to send the indicator to.
​
state
string
required
One of composing (typing), recording (voice note), or paused (stopped typing).
curl -X POST https://api.titan.io/api/sessions/default/messages/typing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "state": "composing"
  }'

​
Mark as seen

Send a read receipt for a specific message. 
curl -X POST https://api.titan.io/api/sessions/default/messages/seen \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "messageId": "ABCDEF123456"
  }'

​
Star and unstar messages

Bookmark important messages using the star endpoints. 
curl -X POST https://api.titan.io/api/sessions/default/messages/star \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "messageId": "ABCDEF123456"
  }'
For high-throughput workloads, add the Prefer: respond-async header to any send request. Titan returns 202 Accepted immediately and delivers the result via a command.result webhook event. See async commands for details.