Skip to main content
GET
/
inbox
/
conversations
curl -X GET "https://api.avoca.ai/v1/inbox/conversations?status=open&channel=voice,sms&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID"

{
  "data": {
    "conversations": [
      {
        "id": "conv_abc123",
        "channel": "voice",
        "status": "open",
        "priority": "urgent",
        "customer": {
          "id": "cust_456",
          "name": "John Smith",
          "phone": "+13105551234",
          "email": "john@email.com",
          "servicetitan_id": "12345"
        },
        "assignee": {
          "id": "user_789",
          "name": "Sarah Johnson",
          "avatar_url": "https://avatars.avoca.ai/sarah.jpg"
        },
        "summary": "No hot water - needs emergency service",
        "messages_count": 1,
        "unread_count": 0,
        "tags": ["emergency", "water_heater"],
        "metadata": {
          "call_duration": 245,
          "recording_url": "https://recordings.avoca.ai/call_abc123.mp3",
          "transcript_available": true
        },
        "created_at": "2024-01-20T14:30:00Z",
        "last_activity_at": "2024-01-20T14:35:00Z",
        "resolved_at": null
      },
      {
        "id": "conv_def456",
        "channel": "sms",
        "status": "pending",
        "priority": "normal",
        "customer": {
          "id": "cust_789",
          "name": "Jane Doe",
          "phone": "+13105555678",
          "email": "jane@email.com",
          "servicetitan_id": "67890"
        },
        "assignee": null,
        "summary": "Question about maintenance plan pricing",
        "messages_count": 3,
        "unread_count": 1,
        "tags": ["sales_inquiry", "maintenance_plan"],
        "metadata": {
          "thread_id": "sms_thread_123"
        },
        "created_at": "2024-01-20T13:00:00Z",
        "last_activity_at": "2024-01-20T14:45:00Z",
        "resolved_at": null
      }
    ],
    "pagination": {
      "total": 47,
      "limit": 10,
      "offset": 0,
      "has_more": true
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-20T15:00:00Z"
  }
}
Coming Soon - The Unified Inbox will provide a single view of all customer communications across channels. Filter, search, and manage conversations from one centralized location.

​
Request

​
status
string
Filter by conversation status:
  • open - Active conversations
  • pending - Awaiting response
  • resolved - Completed conversations
  • all - All conversations (default)
​
channel
array
Filter by communication channels:
  • voice - Phone calls
  • sms - Text messages
  • email - Email threads
  • live_chat - Live chat sessions
​
assignee_id
string
Filter by assigned team member ID
​
customer_id
string
Filter by specific customer ID
​
date_from
string
Start date for conversation filter (ISO 8601)
​
date_to
string
End date for conversation filter (ISO 8601)
​
search
string
Search conversations by content, customer name, or phone number
​
tags
array
Filter by conversation tags
​
priority
string
Filter by priority level:
  • urgent - Requires immediate attention
  • high - Important conversations
  • normal - Standard priority
  • low - Non-urgent items
​
limit
number
default:"20"
Number of conversations to return (max 100)
​
offset
number
default:"0"
Pagination offset
​
sort
string
default:"last_activity_desc"
Sort order:
  • last_activity_desc - Most recent activity first
  • last_activity_asc - Oldest activity first
  • created_desc - Newest conversations first
  • created_asc - Oldest conversations first
  • priority_desc - Highest priority first

​
Response

​
conversations
array
List of conversations
​
pagination
object
Pagination information
curl -X GET "https://api.avoca.ai/v1/inbox/conversations?status=open&channel=voice,sms&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: YOUR_WORKSPACE_ID"

{
  "data": {
    "conversations": [
      {
        "id": "conv_abc123",
        "channel": "voice",
        "status": "open",
        "priority": "urgent",
        "customer": {
          "id": "cust_456",
          "name": "John Smith",
          "phone": "+13105551234",
          "email": "john@email.com",
          "servicetitan_id": "12345"
        },
        "assignee": {
          "id": "user_789",
          "name": "Sarah Johnson",
          "avatar_url": "https://avatars.avoca.ai/sarah.jpg"
        },
        "summary": "No hot water - needs emergency service",
        "messages_count": 1,
        "unread_count": 0,
        "tags": ["emergency", "water_heater"],
        "metadata": {
          "call_duration": 245,
          "recording_url": "https://recordings.avoca.ai/call_abc123.mp3",
          "transcript_available": true
        },
        "created_at": "2024-01-20T14:30:00Z",
        "last_activity_at": "2024-01-20T14:35:00Z",
        "resolved_at": null
      },
      {
        "id": "conv_def456",
        "channel": "sms",
        "status": "pending",
        "priority": "normal",
        "customer": {
          "id": "cust_789",
          "name": "Jane Doe",
          "phone": "+13105555678",
          "email": "jane@email.com",
          "servicetitan_id": "67890"
        },
        "assignee": null,
        "summary": "Question about maintenance plan pricing",
        "messages_count": 3,
        "unread_count": 1,
        "tags": ["sales_inquiry", "maintenance_plan"],
        "metadata": {
          "thread_id": "sms_thread_123"
        },
        "created_at": "2024-01-20T13:00:00Z",
        "last_activity_at": "2024-01-20T14:45:00Z",
        "resolved_at": null
      }
    ],
    "pagination": {
      "total": 47,
      "limit": 10,
      "offset": 0,
      "has_more": true
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2024-01-20T15:00:00Z"
  }
}

​
Conversation Actions

​
Assign Conversation

PUT /inbox/conversations/{conversation_id}/assign
{
  "assignee_id": "user_123"
}

​
Update Status

PUT /inbox/conversations/{conversation_id}/status
{
  "status": "resolved",
  "resolution_notes": "Issue resolved by scheduling service"
}

​
Add Tags

POST /inbox/conversations/{conversation_id}/tags
{
  "tags": ["vip_customer", "recurring_issue"]
}

​
Add Note

POST /inbox/conversations/{conversation_id}/notes
{
  "content": "Customer prefers morning appointments",
  "internal": true
}