Conversations API

List Conversations

GET /v1/{tenantId}/conversations

Query parameters:

Parameter	Type	Default	Description
status	string	active	Filter: active, paused, killed

Request:

curl -s "https://api.squawkpipe.ai/v1/{tenantId}/conversations" \
  -H "Authorization: Bearer $SQUAWK_API_KEY"

Response 200 OK:

[
  {
    "id": "conv_abc123",
    "channel": "whatsapp",
    "contactName": "Sarah Chen",
    "contactRef": "+447700900123",
    "status": "active",
    "unrespondedCount": 2,
    "lastMessagePreview": "Hi, I need to change my delivery address",
    "lastMessageAt": "2026-04-05T14:30:00Z",
    "createdAt": "2026-04-05T14:00:00Z"
  }
]

---

Get Conversation

GET /v1/{tenantId}/conversations/{conversationId}

Request:

curl -s "https://api.squawkpipe.ai/v1/{tenantId}/conversations/conv_abc123" \
  -H "Authorization: Bearer $SQUAWK_API_KEY"

Response 200 OK:

{
  "conversation": {
    "id": "conv_abc123",
    "channel": "whatsapp",
    "contactName": "Sarah Chen",
    "contactRef": "+447700900123",
    "status": "active",
    "unrespondedCount": 2
  },
  "contact": {
    "contactId": "contact_001",
    "fullName": "Sarah Chen",
    "phone": "+447700900123",
    "email": null,
    "agentMuted": false,
    "notes": []
  },
  "messages": [
    {
      "id": "msg_1",
      "messageType": "message",
      "senderType": "contact",
      "senderName": "Sarah Chen",
      "body": "Hi, I need to change my delivery address",
      "createdAt": "2026-04-05T14:30:00Z"
    },
    {
      "id": "msg_2",
      "messageType": "message",
      "senderType": "agent",
      "senderName": "Support Agent",
      "body": "Of course! What's your order number?",
      "createdAt": "2026-04-05T14:31:00Z"
    }
  ]
}

---

Create Conversation

POST /v1/conversations

Request body:

{
  "channel": "email",
  "channelRef": "thread_001",
  "contactName": "Sarah Chen",
  "contactRef": "sarah@example.com"
}

Request:

curl -X POST "https://api.squawkpipe.ai/v1/conversations" \
  -H "Authorization: Bearer $SQUAWK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","channelRef":"thread_001","contactName":"Sarah Chen","contactRef":"sarah@example.com"}'

Response 201 Created: Returns the new conversation object.

---

Send a Message

POST /v1/{tenantId}/conversations/{conversationId}/messages

Request body:

Field	Type	Description
body	string	Message content
senderType	string	"agent" or "supervisor"
senderName	string	Display name of the sender

Request:

curl -X POST "https://api.squawkpipe.ai/v1/{tenantId}/conversations/conv_abc123/messages" \
  -H "Authorization: Bearer $SQUAWK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Your order has been shipped!","senderType":"agent","senderName":"Support Agent"}'

Response 200 OK:

{
  "id": "msg_xyz789",
  "body": "Your order has been shipped!",
  "senderType": "agent",
  "createdAt": "2026-04-05T14:35:00Z"
}

409 Conflict

If the conversation is paused or permanently ended, the API returns 409 Conflict. Do not retry — wait for a supervisor to resume the conversation.