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.

The contacts API lets you query the contacts visible to a session, look up profile information, verify which phone numbers are registered on WhatsApp, and manage your block list. All contact endpoints are scoped to a session — contact data reflects what that WhatsApp account can see.

​
Contact object

​
phoneNumber
string
Phone number in E.164 format (e.g. +5511999999999).
​
pushName
string
Display name set by the contact on their WhatsApp account.
​
name
string
Saved contact name in the session account’s address book.
​
businessName
string
Business name for WhatsApp Business accounts.
​
lid
string
Linked Device ID of the contact.
​
profileUrl
string
URL of the contact’s profile picture.

​
List contacts

curl https://api.example.com/api/sessions/default/contacts \
  -H "Authorization: Bearer titan_..."
GET /api/sessions/{session}/contacts Returns all contacts visible to the session.
​
session
string
required
Session name.
{
  "data": [
    {
      "phoneNumber": "+5511999999999",
      "pushName": "João Silva",
      "name": "João",
      "lid": "12345678901234567890@lid"
    }
  ]
}

​
Get a contact

curl https://api.example.com/api/sessions/default/contacts/5511999999999%40s.whatsapp.net \
  -H "Authorization: Bearer titan_..."
GET /api/sessions/{session}/contacts/{contactId} Returns profile information for a specific contact.
​
session
string
required
Session name.
​
contactId
string
required
Contact JID (URL-encoded), e.g. 5511999999999%40s.whatsapp.net.
{
  "data": {
    "phoneNumber": "+5511999999999",
    "pushName": "João Silva",
    "name": "João",
    "businessName": null,
    "lid": "12345678901234567890@lid",
    "profileUrl": "https://pps.whatsapp.net/v/..."
  }
}

​
Get a contact’s profile picture

curl https://api.example.com/api/sessions/default/contacts/5511999999999%40s.whatsapp.net/picture \
  -H "Authorization: Bearer titan_..."
GET /api/sessions/{session}/contacts/{contactId}/picture Returns the profile picture URL for a contact. Returns 404 if the contact has no profile picture or has restricted visibility.
​
session
string
required
Session name.
​
contactId
string
required
Contact JID (URL-encoded).
{
  "data": {
    "url": "https://pps.whatsapp.net/v/t61.24694-24/..."
  }
}

​
Check if phone numbers are on WhatsApp

curl -X POST https://api.example.com/api/sessions/default/contacts/check \
  -H "Authorization: Bearer titan_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+5511999999999", "+14155552671"]
  }'
POST /api/sessions/{session}/contacts/check Checks whether one or more phone numbers are registered on WhatsApp. Useful for validating numbers before sending messages.
​
session
string
required
Session name.
​
phoneNumbers
string[]
required
Array of phone numbers to check in E.164 format (e.g. +5511999999999).
​
phoneNumber
string
The normalized phone number that was checked.
​
exists
boolean
Whether the number is registered on WhatsApp.
​
lid
string
Linked Device ID. Present when exists is true.
{
  "data": [
    {
      "phoneNumber": "+5511999999999",
      "exists": true,
      "lid": "12345678901234567890@lid"
    },
    {
      "phoneNumber": "+14155552671",
      "exists": false
    }
  ]
}

​
Block a contact

curl -X POST https://api.example.com/api/sessions/default/contacts/5511999999999%40s.whatsapp.net/block \
  -H "Authorization: Bearer titan_..."
POST /api/sessions/{session}/contacts/{contactId}/block Blocks a contact. Blocked contacts cannot send messages to the session account.
​
session
string
required
Session name.
​
contactId
string
required
Contact JID (URL-encoded).
{
  "data": { "success": true, "message": "contact blocked" }
}

​
Unblock a contact

curl -X DELETE https://api.example.com/api/sessions/default/contacts/5511999999999%40s.whatsapp.net/block \
  -H "Authorization: Bearer titan_..."
DELETE /api/sessions/{session}/contacts/{contactId}/block Unblocks a previously blocked contact.
​
session
string
required
Session name.
​
contactId
string
required
Contact JID (URL-encoded).
{
  "data": { "success": true, "message": "contact unblocked" }
}