REST API endpoints for conversations

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

string

Unique identifier for the conversation, prefixed with conv_.

string

ID of the contact this conversation is with.

string

The messaging channel. One of whatsapp, instagram, messenger, or webchat.

string

Current conversation status. One of open or resolved.

object

The agent or team the conversation is assigned to, or null if unassigned.

Show properties

string

Either user or team.

string

ID of the assigned user or team.

string

Display name of the assigned user or team.

object[]

Array of Message objects in the conversation, ordered oldest-first. See the Messages reference for the Message object schema.

string

ISO 8601 timestamp of when the conversation was created.

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.

string

default:"open"

Filter by conversation status. One of open, resolved, or all.

string

Filter by channel. One of whatsapp, instagram, messenger, or webchat.

string

Filter by the ID of the user the conversation is assigned to.

number

default:"1"

Page number to retrieve.

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'

const params = new URLSearchParams({
  status: 'open',
  channel: 'whatsapp',
  limit: 20,
});
const response = await fetch(`https://api.waply.io/v1/conversations?${params}`, {
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});
const { data, total, page } = await response.json();

import requests, os

response = requests.get(
    'https://api.waply.io/v1/conversations',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    params={'status': 'open', 'channel': 'whatsapp', 'limit': 20},
)
result = response.json()

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.

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'

const response = await fetch('https://api.waply.io/v1/conversations/conv_01HABC', {
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});
const conversation = await response.json();

import requests, os

response = requests.get(
    'https://api.waply.io/v1/conversations/conv_01HABC',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
)
conversation = response.json()

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.

string

required

The ID of the conversation to assign.

string

ID of the user to assign the conversation to.

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"}'

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 '{"team_id": "team_01H222"}'

await fetch('https://api.waply.io/v1/conversations/conv_01HABC/assign', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user_id: 'usr_01H111' }),
});

import requests, os

requests.post(
    'https://api.waply.io/v1/conversations/conv_01HABC/assign',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={'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.

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'

await fetch('https://api.waply.io/v1/conversations/conv_01HABC/resolve', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.WAPLY_API_KEY}` },
});

import requests, os

requests.post(
    'https://api.waply.io/v1/conversations/conv_01HABC/resolve',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_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.

string

required

The ID of the conversation to add a note to.

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."}'

await fetch('https://api.waply.io/v1/conversations/conv_01HABC/notes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.WAPLY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    content: 'Customer is on the Enterprise plan. Check their Salesforce record before responding.',
  }),
});

import requests, os

requests.post(
    'https://api.waply.io/v1/conversations/conv_01HABC/notes',
    headers={'Authorization': f'Bearer {os.environ["WAPLY_API_KEY"]}'},
    json={'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"
}

API

Endpoints

REST API endpoints for conversations — Waply API

The Conversation object

List conversations

GET /conversations

Get a conversation

GET /conversations/

Assign a conversation

POST /conversations//assign

Resolve a conversation

POST /conversations//resolve

Add an internal note

POST /conversations//notes

​The Conversation object

​List conversations

​GET /conversations

​Get a conversation

​GET /conversations/

​Assign a conversation

​POST /conversations//assign

​Resolve a conversation

​POST /conversations//resolve

​Add an internal note

​POST /conversations//notes

The Conversation object

List conversations

GET /conversations

Get a conversation

GET /conversations/

Assign a conversation

POST /conversations//assign

Resolve a conversation

POST /conversations//resolve

Add an internal note

POST /conversations//notes