PersonaDesk.ai API

The API uses bearer tokens for authentication. Include your key in the Authorization header:

curl https://api.personadesk.ai/v1/tenants \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

• Tenants – represents a single customer account and configuration.
• Agents – AI reception agents or human endpoints that handle conversations.
• Conversations – calls, chats, or sessions with callers and visitors.
• Messages – individual turns within a conversation, including AI and human messages.

GET /v1/conversations?tenant_id=TENANT_ID
Host: api.personadesk.ai
Authorization: Bearer YOUR_API_KEY

{
  "data": [
    {
      "id": "conv_123",
      "tenant_id": "TENANT_ID",
      "status": "completed",
      "channel": "voice",
      "started_at": "2025-01-15T10:24:00Z",
      "ended_at": "2025-01-15T10:26:45Z"
    }
  ],
  "next_cursor": null
}

Configure webhooks to receive POST requests when important events occur, such as a new call starting, a conversation being routed, or a human handoff being requested.

• call.started – a new inbound call has started.
• conversation.routed – a conversation has been routed to an agent or queue.
• handoff.requested – AI has requested a human join or take over.
• conversation.completed – a call or session has ended and metadata is finalized.

{
  "type": "conversation.routed",
  "id": "evt_123",
  "created_at": "2025-01-15T10:25:12Z",
  "data": {
    "conversation_id": "conv_123",
    "tenant_id": "TENANT_ID",
    "from_number": "+15551234567",
    "to_agent_id": "agent_abc",
    "route_reason": "lead_high_intent"
  }
}