Sign In

Conversations

A conversation is the thread between one contact and one channel. Its handler decides who replies: HUMAN, AI or PLUGIN.

List conversations

Newest activity first. Filter with status, channelId or contactId. Page with limit (max 100) and before (an ISO date from the last item).

Scopeconversation:read
statusOPEN | PENDING | SNOOZED | RESOLVED
app.docs.v1.conversation.list.params.status
contactIdstring
app.docs.v1.conversation.list.params.contactId
channelIdstring
app.docs.v1.conversation.list.params.channelId
limitnumber
app.docs.v1.conversation.list.params.limit
beforeISO date
app.docs.v1.conversation.list.params.before
GEThttps://www.beamvia.com/api/v1/conversation
Open
curl -X GET "https://www.beamvia.com/api/v1/conversation?status=OPEN&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "conversations": [
      {
        "id": "6650f0c2a1b2c3d4e5f60700",
        "channelId": "6650f0c2a1b2c3d4e5f60100",
        "contactId": "6650f0c2a1b2c3d4e5f60690",
        "status": "OPEN",
        "priority": "NONE",
        "handler": {
          "type": "HUMAN",
          "memberId": null,
          "divisionId": null
        },
        "tagIds": [],
        "unread": 2,
        "last": {
          "message": {
            "preview": "Is my order shipped?",
            "direction": "INBOUND",
            "at": "2026-10-20T08:00:00.000Z"
          }
        },
        "snooze": {
          "until": null
        },
        "reply": {
          "firstAt": null
        },
        "waiting": {
          "since": "2026-10-20T07:58:00.000Z"
        },
        "createdAt": "2026-10-19T10:00:00.000Z",
        "updatedAt": "2026-10-20T08:00:00.000Z"
      }
    ]
  }
}

List messages

Newest first, 50 by default (limit max 100). Pass before (an ISO date) to load older messages.

Scopeconversation:read
limitnumber
app.docs.v1.conversation.messages.params.limit
beforeISO date
app.docs.v1.conversation.messages.params.before
GEThttps://www.beamvia.com/api/v1/conversation/:conversationId/message
Latest
curl -X GET "https://www.beamvia.com/api/v1/conversation/6650f0c2a1b2c3d4e5f60700/message?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "messages": [
      {
        "id": "6650f0c2a1b2c3d4e5f60718",
        "direction": "INBOUND",
        "author": {
          "type": "CONTACT",
          "contactId": "6650f0c2a1b2c3d4e5f60690"
        },
        "content": {
          "type": "TEXT",
          "text": "Is my order shipped?"
        },
        "status": "SENT",
        "sentAt": "2026-10-20T08:00:00.000Z"
      }
    ]
  }
}

Change status

Set OPEN, PENDING, SNOOZED or RESOLVED. Resolving hands the conversation back to the channel's default handler.

Scopeconversation:write
statusOPEN | PENDING | SNOOZED | RESOLVEDrequired
app.docs.v1.conversation.status.params.status
snooze.untilISO date
app.docs.v1.conversation.status.params.snoozedUntil
POSThttps://www.beamvia.com/api/v1/conversation/:conversationId/status
Resolve
curl -X POST "https://www.beamvia.com/api/v1/conversation/6650f0c2a1b2c3d4e5f60700/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "RESOLVED"
  }'
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "conversation": {
      "id": "6650f0c2a1b2c3d4e5f60700",
      "channelId": "6650f0c2a1b2c3d4e5f60100",
      "contactId": "6650f0c2a1b2c3d4e5f60690",
      "status": "RESOLVED",
      "priority": "NONE",
      "handler": {
        "type": "HUMAN",
        "memberId": null,
        "divisionId": null
      },
      "tagIds": [],
      "unread": 0,
      "last": {
        "message": {
          "preview": "Is my order shipped?",
          "direction": "INBOUND",
          "at": "2026-10-20T08:00:00.000Z"
        }
      },
      "snooze": {
        "until": null
      },
      "reply": {
        "firstAt": null
      },
      "waiting": {
        "since": "2026-10-20T07:58:00.000Z"
      },
      "createdAt": "2026-10-19T10:00:00.000Z",
      "updatedAt": "2026-10-20T08:00:00.000Z"
    }
  }
}

Change handler

Hand the conversation to people ({ "type": "HUMAN" }) or an AI agent ({ "type": "AI", "agentId": "…" }), for example to pause the AI.

Scopeconversation:write
handlerobjectrequired
app.docs.v1.conversation.handler.params.handler
POSThttps://www.beamvia.com/api/v1/conversation/:conversationId/handler
curl -X POST "https://www.beamvia.com/api/v1/conversation/6650f0c2a1b2c3d4e5f60700/handler" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "handler": {
      "type": "HUMAN",
      "memberId": null
    }
  }'
200 OK
{
  "status": true,
  "message": "OK",
  "data": {
    "conversation": {
      "id": "6650f0c2a1b2c3d4e5f60700",
      "channelId": "6650f0c2a1b2c3d4e5f60100",
      "contactId": "6650f0c2a1b2c3d4e5f60690",
      "status": "OPEN",
      "priority": "NONE",
      "handler": {
        "type": "AI",
        "agentId": "6650f0c2a1b2c3d4e5f60800"
      },
      "tagIds": [],
      "unread": 2,
      "last": {
        "message": {
          "preview": "Is my order shipped?",
          "direction": "INBOUND",
          "at": "2026-10-20T08:00:00.000Z"
        }
      },
      "snooze": {
        "until": null
      },
      "reply": {
        "firstAt": null
      },
      "waiting": {
        "since": "2026-10-20T07:58:00.000Z"
      },
      "createdAt": "2026-10-19T10:00:00.000Z",
      "updatedAt": "2026-10-20T08:00:00.000Z"
    }
  }
}