Skip to main content
Conversations in Waply represent the thread of messages between you and a contact on a particular channel. Each conversation has a status, an optional assignee, and a log of all messages exchanged. Use the conversations API to build custom inboxes, automate triage, or integrate Waply into your support tooling.

​
The Conversation object

​
id
string
Unique identifier for the conversation, prefixed with conv_.
​
contact_id
string
ID of the contact this conversation is with.
​
channel
string
The messaging channel. One of whatsapp, instagram, messenger, or webchat.
​
status
string
Current conversation status. One of open or resolved.
​
assigned_to
object
The agent or team the conversation is assigned to, or null if unassigned.
​
messages
object[]
Array of Message objects in the conversation, ordered oldest-first. See the Messages reference for the Message object schema.
​
created_at
string
ISO 8601 timestamp of when the conversation was created.
​
updated_at
string
ISO 8601 timestamp of the most recent activity in the conversation.

​
List conversations

​
GET /conversations

Returns a paginated list of conversations. Filter by status, channel, or assigned agent.
​
status
string
default:"open"
Filter by conversation status. One of open, resolved, or all.
​
channel
string
Filter by channel. One of whatsapp, instagram, messenger, or webchat.
​
assigned_to
string
Filter by the ID of the user the conversation is assigned to.
​
page
number
default:"1"
Page number to retrieve.
​
limit
number
default:"20"
Number of conversations per page. Maximum is 100.
curl --request GET \
  --url 'https://api.waply.io/v1/conversations?status=open&channel=whatsapp&limit=20' \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response 
{
  "data": [
    {
      "id": "conv_01HABC",
      "contact_id": "con_01HXYZ",
      "channel": "whatsapp",
      "status": "open",
      "assigned_to": {
        "type": "user",
        "id": "usr_01H111",
        "name": "Alice Support"
      },
      "messages": [],
      "created_at": "2026-04-15T08:30:00Z",
      "updated_at": "2026-04-16T09:12:00Z"
    }
  ],
  "total": 38,
  "page": 1
}

​
Get a conversation

​
GET /conversations/

Returns a single conversation including its full message history.
​
id
string
required
The ID of the conversation to retrieve.
curl --request GET \
  --url https://api.waply.io/v1/conversations/conv_01HABC \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response 
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "open",
  "assigned_to": null,
  "messages": [
    {
      "id": "msg_01HMNO",
      "conversation_id": "conv_01HABC",
      "direction": "inbound",
      "type": "text",
      "content": "Hello, I need help with my order.",
      "status": "delivered",
      "created_at": "2026-04-16T09:10:00Z"
    }
  ],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T09:10:00Z"
}

​
Assign a conversation

​
POST /conversations//assign

Assigns a conversation to a specific agent or team. Provide either user_id or team_id, not both.
​
id
string
required
The ID of the conversation to assign.
​
user_id
string
ID of the user to assign the conversation to.
​
team_id
string
ID of the team to assign the conversation to.
curl --request POST \
  --url https://api.waply.io/v1/conversations/conv_01HABC/assign \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"user_id": "usr_01H111"}'
Response Returns the updated Conversation object with assigned_to populated. 
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "open",
  "assigned_to": {
    "type": "user",
    "id": "usr_01H111",
    "name": "Alice Support"
  },
  "messages": [],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T10:00:00Z"
}

​
Resolve a conversation

​
POST /conversations//resolve

Marks a conversation as resolved. Resolved conversations no longer appear in the default open inbox view. You can reopen a resolved conversation by assigning or replying to it.
​
id
string
required
The ID of the conversation to resolve.
curl --request POST \
  --url https://api.waply.io/v1/conversations/conv_01HABC/resolve \
  --header 'Authorization: Bearer YOUR_API_KEY'
Response Returns the updated Conversation object with status set to resolved. 
{
  "id": "conv_01HABC",
  "contact_id": "con_01HXYZ",
  "channel": "whatsapp",
  "status": "resolved",
  "assigned_to": null,
  "messages": [],
  "created_at": "2026-04-16T09:10:00Z",
  "updated_at": "2026-04-16T10:15:00Z"
}

​
Add an internal note

​
POST /conversations//notes

Adds an internal note to a conversation. Notes are only visible to your team — they are never sent to the contact.
​
id
string
required
The ID of the conversation to add a note to.
​
content
string
required
The text content of the internal note.
curl --request POST \
  --url https://api.waply.io/v1/conversations/conv_01HABC/notes \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"content": "Customer is on the Enterprise plan. Check their Salesforce record before responding."}'
Response 
{
  "id": "note_01HPQR",
  "conversation_id": "conv_01HABC",
  "content": "Customer is on the Enterprise plan. Check their Salesforce record before responding.",
  "created_at": "2026-04-16T10:20:00Z"
}