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 Python SDK provides a typed client for the Titan WhatsApp API. It supports Python 3.9 and later. Types are auto-generated from the OpenAPI spec so they stay in sync with every API release. The SDK includes webhook signature verification and accepts both server API keys and client tokens.

​
Installation

pip install titan-sdk

​
Create a client

from titan import TitanClient

client = TitanClient(base_url="https://api.example.com", api_key="titan_...")
Keep your API key on the server. Use client tokens for any code that runs in the browser or an untrusted environment.

​
Send a message

resp = client.messages.send("default", {
    "chatId": "[email protected]",
    "type": "text",
    "text": "Hello from Python!",
})
The first argument is the session name. The second is the message payload as a dict. The response is a typed object matching the API’s JSON response shape.

​
Service domains

The client exposes every Titan API domain as an attribute. Python uses snake_case for all attribute names.
DomainAttribute
Sessionsclient.sessions
Messagesclient.messages
Contactsclient.contacts
Groupsclient.groups
Channelsclient.channels
Presenceclient.presence
Profileclient.profile
Labelsclient.labels
Chatsclient.chats
Webhooksclient.webhooks
Pairingclient.pairing
LIDsclient.lids
Mediaclient.media
Client tokensclient.client_tokens
The client tokens domain uses client_tokens (with an underscore) in Python, following snake_case conventions. In TypeScript and PHP it is clientTokens.

​
Webhook verification

Use verify_webhook to validate the HMAC-SHA256 signature on incoming webhook deliveries. It returns True if the signature is valid and False otherwise. 
from titan import verify_webhook

is_valid = verify_webhook(raw_body, signature_header, secret)
Pass the raw request body as bytes, the value of the X-Webhook-Signature header, and your webhook secret.
Always verify webhook signatures before processing events. Reject requests with invalid signatures with a 400 or 401 response.

​
Client tokens

To use a short-lived client token instead of a server API key, pass client_token instead of api_key: 
client = TitanClient(base_url="...", client_token="titan_ct_...")

​
Full client token flow

from titan import TitanClient

# Server-side: mint a token
server = TitanClient(base_url="https://api.example.com", api_key="titan_...")

token = server.client_tokens.mint({
    "session": "default",
    "ephemeralId": "user-123",
    "ttl": 900,
})

# Browser/restricted client: use the token
browser = TitanClient(base_url="https://api.example.com", client_token=token["token"])
See Client tokens for how to configure session rules and control what client tokens can do.

​
Types

Types are auto-generated from the OpenAPI spec into python/titan/types_gen.py in the titan-api/sdks monorepo. They are regenerated automatically whenever the spec changes. You can import them directly for type annotations: 
from titan.types_gen import SendMessageRequest, SessionStatus

​
Deprecation warnings

The SDK reads Deprecation, Sunset, and Titan-SDK-Deprecation response headers on every API response. When any of these headers appear, the SDK emits a warning once per client lifetime:
  • Deprecation: true — the API version you are calling is deprecated.
  • Sunset: <date> — the API version will be removed on the given date.
  • Titan-SDK-Deprecation — your installed SDK version is outdated.
Warnings are emitted once per client instance to keep logs readable. If you initialize a new client on every request, each instance will emit the warning independently.