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 gives you full programmatic control over WhatsApp groups. You can create groups, update their metadata, manage participants, promote admins, generate invite links, and listen for group events — all without touching the WhatsApp app. Every endpoint is scoped to a {session}, which is the name of the WhatsApp session performing the operation.
To send a message to a group, use the send messages endpoint with the group’s JID as the chatId (e.g. [email protected]).

​
Group lifecycle

​
Create a group

POST /api/sessions/{session}/groups
​
name
string
required
The group’s display name (subject).
​
participants
string[]
required
Array of JIDs to add as initial members (e.g. ["[email protected]"]). The session account is added as the group creator automatically.
curl -X POST https://api.titan.io/api/sessions/default/groups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Updates",
    "participants": [
      "[email protected]",
      "[email protected]"
    ]
  }'

​
List groups

Retrieve all groups the session is a member of. 
GET /api/sessions/{session}/groups

​
Get group info

Fetch full details for a single group, including its participants. 
GET /api/sessions/{session}/groups/{groupId}
The response includes the group’s id, name, description, createdAt, ownerLid, and a participants array.

​
Leave a group

Remove the session account from the group. 
POST /api/sessions/{session}/groups/{groupId}/leave

​
Delete a group

Delete a group you own. Only the group creator can call this endpoint. 
DELETE /api/sessions/{session}/groups/{groupId}

​
Update group settings

​
Update the group name

PUT /api/sessions/{session}/groups/{groupId}/subject

curl -X PUT https://api.titan.io/api/sessions/default/groups/[email protected]/subject \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "New Group Name"}'

​
Update the description

PUT /api/sessions/{session}/groups/{groupId}/description

curl -X PUT https://api.titan.io/api/sessions/default/groups/[email protected]/description \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value": "Weekly team sync — every Monday at 10 AM"}'

​
Set a profile picture

Pass an image URL or base64-encoded JPEG. 
PUT /api/sessions/{session}/groups/{groupId}/picture

curl -X PUT https://api.titan.io/api/sessions/default/groups/[email protected]/picture \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/team-avatar.jpg"}'

​
Participant management

​
List participants

GET /api/sessions/{session}/groups/{groupId}/participants
Each entry in the response includes:
  • phoneNumber — participant’s phone number (when available)
  • lid — Linked Device ID
  • isAdmin — whether the participant is an admin
  • isSuperAdmin — whether the participant is the group creator

​
Add participants

POST /api/sessions/{session}/groups/{groupId}/participants
​
participants
string[]
required
JIDs to add (e.g. ["[email protected]"]). Up to 256 per request.
curl -X POST https://api.titan.io/api/sessions/default/groups/[email protected]/participants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": ["[email protected]"]
  }'

​
Remove participants

DELETE /api/sessions/{session}/groups/{groupId}/participants
Pass the same participants array in the request body. Only group admins can remove participants.

​
Promote to admin

POST /api/sessions/{session}/groups/{groupId}/participants/promote

curl -X POST https://api.titan.io/api/sessions/default/groups/[email protected]/participants/promote \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": ["[email protected]"]
  }'

​
Demote from admin

POST /api/sessions/{session}/groups/{groupId}/participants/demote
Pass the same body structure as promote. Only the group super admin (creator) can demote other admins. 
GET /api/sessions/{session}/groups/{groupId}/invite
Returns {"code": "ABcDeFgHiJk"}. The full WhatsApp invite URL is https://chat.whatsapp.com/{code}. 
DELETE /api/sessions/{session}/groups/{groupId}/invite
Revoke the current link and generate a new one. Anyone with the old link will no longer be able to join.

​
Preview a group before joining

Check what group an invite link points to before joining. 
GET /api/sessions/{session}/groups/join?inviteCode=ABcDeFgHiJk
Returns a GroupInviteInfo object with the group’s subject, member count, and participant list. 
POST /api/sessions/{session}/groups/join
​
code
string
required
The invite code from the WhatsApp link (not the full URL — just the code after chat.whatsapp.com/).
curl -X POST https://api.titan.io/api/sessions/default/groups/join \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "ABcDeFgHiJk"}'

​
Webhook events

Titan emits two group-related webhook events:

​
group.update

Fires when a group’s settings change — such as a new subject, description, or when the session joins a group via invite. Key fields in the payload:
  • id — the group JID
  • newSubject — present when the group name changed
  • newDescription — present when the description changed
  • action — set to "joined" when the session joined via invite link

​
group.participant

Fires when membership changes in any group the session belongs to. Key fields in the payload:
  • id — the group JID
  • joined — array of JIDs who joined
  • left — array of JIDs who left
  • promoted — array of JIDs promoted to admin
  • demoted — array of JIDs demoted from admin
Use group.participant events to keep your own participant lists in sync without polling the list endpoint.