Conversations API — List, Create, and Update Threads

The Conversations API lets you read and manage conversation threads in your Sahut inbox programmatically. Use it to pull conversation data into your reporting tools, create conversations from external triggers, or update conversation status and assignments.

List conversations

Retrieve a paginated list of conversations in your workspace.

GET /conversations

Query parameters

string

Filter by status. One of: open, pending, resolved, snoozed. Omit to return all statuses.

string

Filter by channel ID. Returns only conversations from that channel.

string

Filter by assigned agent ID. Use unassigned to get conversations with no assignee.

integer

Page number for pagination. Default: 1.

integer

Number of results per page. Default: 25. Max: 100.

Example request

curl "https://api.sahut.id/v1/conversations?status=open&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "conv_01HX2B9K3M5N7P",
      "status": "open",
      "channel": {
        "id": "ch_01HX1A8J2L4M6N",
        "type": "whatsapp",
        "name": "WhatsApp Utama"
      },
      "contact": {
        "id": "ct_01HX3C0L4N6P8Q",
        "name": "Budi Santoso",
        "phone": "+628123456789"
      },
      "assignee": {
        "id": "usr_01HX0Z7I1K3L5M",
        "name": "Sari Dewi"
      },
      "labels": ["follow-up"],
      "created_at": "2024-03-15T08:30:00Z",
      "updated_at": "2024-03-15T09:15:00Z"
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 10,
    "total_pages": 5
  }
}

Get a conversation

Retrieve a single conversation by its ID.

GET /conversations/{id}

Path parameters

string

required

The conversation ID (e.g., conv_01HX2B9K3M5N7P).

Example request

curl https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a conversation

Start a new conversation. This creates an outbound conversation — useful for proactive outreach.

POST /conversations

Request body

string

required

ID of the contact to start the conversation with.

string

required

ID of the channel to use for this conversation.

object

Optional initial message to send. Include content (string) for a text message, or template_id for a WhatsApp template message.

string

Agent ID to assign the conversation to immediately.

Example request

curl -X POST https://api.sahut.id/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "ct_01HX3C0L4N6P8Q",
    "channel_id": "ch_01HX1A8J2L4M6N",
    "message": {
      "content": "Halo Budi, ada yang bisa kami bantu?"
    }
  }'

Update a conversation

Change a conversation’s status, assignee, or labels.

PATCH /conversations/{id}

Request body

string

New status. One of: open, pending, resolved, snoozed.

string

Agent ID to assign to. Pass null to unassign.

string

Team ID to assign to.

array

Array of label names to set on the conversation. Replaces existing labels.

Example request

curl -X PATCH https://api.sahut.id/v1/conversations/conv_01HX2B9K3M5N7P \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "labels": ["resolved-billing"]
  }'

Overview

Endpoints

Conversations API — List, Create, and Update Threads

List conversations

Query parameters

Example request

Example response

Get a conversation

Path parameters

Example request

Create a conversation

Request body

Example request

Update a conversation

Request body

Example request

​List conversations

​Query parameters

​Example request

​Example response

​Get a conversation

​Path parameters

​Example request

​Create a conversation

​Request body

​Example request

​Update a conversation

​Request body

​Example request

List conversations

Query parameters

Example request

Example response

Get a conversation

Path parameters

Example request

Create a conversation

Request body

Example request

Update a conversation

Request body

Example request