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.

This guide walks you through everything you need to send your first WhatsApp message with Titan. By the end, you will have a connected session and a working API call you can build on. All examples use curl; if you prefer an SDK, see the SDKs overview.
1

Get an API key

Before you can call the API, you need an API key. API keys use the titan_ prefix and are passed as a Bearer token on every request.If you are using the SaaS edition, create a key from your account dashboard. You can also create one via the API itself once you have an initial key:
curl --request POST \
  --url https://api.example.com/api/account/keys \
  --header 'Authorization: Bearer titan_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "label": "my-first-key",
    "lifetimeDays": 30,
    "scopes": ["sessions:manage", "messages:write"]
  }'
The response includes the full key — store it securely, it is only returned once:
{
  "data": {
    "id": "key_01jz...",
    "key": "titan_AAAB...",
    "label": "my-first-key",
    "scopes": ["sessions:manage", "messages:write"],
    "createdAt": "2025-05-01T12:00:00Z",
    "expiresAt": "2025-05-31T12:00:00Z"
  }
}
For a first test, request the * (all scopes) permission so you are not blocked by missing scopes. Narrow the scopes down once your integration is working.
2

Create a session

A session represents one WhatsApp number connected to Titan. Session names must be alphanumeric and may include dots, hyphens, and underscores (1–64 characters).
curl --request POST \
  --url https://api.example.com/api/sessions \
  --header 'Authorization: Bearer titan_...' \
  --header 'Content-Type: application/json' \
  --data '{"name": "my-session"}'
Expected response:
{
  "data": {
    "name": "my-session",
    "status": "DISCONNECTED",
    "statusReason": null,
    "createdAt": "2025-05-01T12:01:00Z"
  }
}
Now start the session so it is ready for pairing:
curl --request POST \
  --url https://api.example.com/api/sessions/my-session/start \
  --header 'Authorization: Bearer titan_...'
The session moves to CONNECTING status and waits for you to pair a WhatsApp number.
3

Pair your WhatsApp number

You can pair using a QR code scan or an 8-digit phone code. Choose whichever method suits your setup.
Retrieve the QR code as a base64-encoded PNG:
curl --request GET \
  --url https://api.example.com/api/sessions/my-session/pairing/qr \
  --header 'Authorization: Bearer titan_...'
Response:
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
Decode the base64 value and display it as an image, then open WhatsApp on your phone, go to Linked devices, tap Link a device, and scan the code.
QR codes expire after a short window. If scanning fails, request a fresh QR code and try again.
Once you complete pairing, the session status moves to CONNECTED. You can verify this by checking the session:
curl --request GET \
  --url https://api.example.com/api/sessions/my-session \
  --header 'Authorization: Bearer titan_...'

{
  "data": {
    "name": "my-session",
    "status": "CONNECTED",
    "statusReason": null
  }
}
4

Send a message

With your session connected, send a text message using the unified send endpoint. The chatId is the recipient’s phone number in WhatsApp JID format: {phone}@s.whatsapp.net.
curl --request POST \
  --url https://api.example.com/api/messages/send \
  --header 'Authorization: Bearer titan_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "session": "my-session",
    "chatId": "[email protected]",
    "type": "text",
    "text": "Hello from Titan!"
  }'
Expected response:
{
  "data": {
    "id": "msg_3AFBWAIKiNsZCmkg...",
    "session": "my-session",
    "fromMe": true,
    "status": "sent",
    "type": "text",
    "text": "Hello from Titan!",
    "sentAt": "2025-05-01T12:05:00Z"
  }
}
To send to a group, use the group JID as chatId (format: {id}@g.us). To post a WhatsApp Status (story), set chatId to status@broadcast.

​
What’s next

Now that you have sent your first message, explore what else you can do:

Send media messages

Send images, video, audio, documents, polls, and location messages using the same unified endpoint.

Receive incoming messages

Set up a webhook to receive message.received events and build a two-way conversation.

Use an SDK

Replace raw curl calls with a typed client in TypeScript, Go, Python, PHP, or C#.

Manage sessions

Learn about session lifecycle, auto-reconnect, status reasons, and per-session configuration.