Sign in
Webchat

Create a new webchat session.

Creates a new webchat visitor session for the given widget. Always creates a brand-new session.

post/webchat_sessions

Request body

widget_idstring uuid required

The widget to create the session for. Returned from the POST /widgets or GET /widgets response.

page_urlstring

The URL of the page the widget was embedded on when this session was created. Captured client-side from window.location.href at session-creation time; not re-captured on subsequent navigation within the same session.

referrerstring

document.referrer at session-creation time -- the page the visitor was on immediately before arriving at the page that embeds the widget. Distinct from page_url (the page the widget is currently embedded on). Captured client-side; not re-captured on subsequent navigation within the same session.

Example request

{
  "widget_id": "550e8400-e29b-41d4-a716-446655440000",
  "page_url": "https://example.com/pricing",
  "referrer": "https://example.com/blog/some-article"
}

Response

Details of the created session.

idstring uuid required

The unique identifier of the session, and the visitor's continuity token. Returned from the POST /sessions or GET /sessions response.

customer_idstring uuid required

The unique identifier of the associated customer. Returned from the GET /customers response.

widget_idstring uuid required

The widget this session belongs to. Returned from the POST /widgets or GET /widgets response.

status'active' | 'ended' required

The status of the session.

page_urlstring

The URL of the page the widget was embedded on when this session was created. Captured client-side from window.location.href at session-creation time; not re-captured on subsequent navigation within the same session.

referrerstring

document.referrer at session-creation time -- the page the visitor was on immediately before arriving at the page that embeds the widget. Distinct from page_url (the page the widget is currently embedded on). Captured client-side; not re-captured on subsequent navigation within the same session.

tm_last_activitystring date-time

Timestamp of the last activity on this session.

tm_createstring date-time

Timestamp when the session was created.

tm_updatestring date-time

Timestamp when the session was last updated.

tm_endstring date-time

Timestamp when the session ended.

Example response

{
  "id": "7a1bcb1a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "widget_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "page_url": "https://example.com/pricing",
  "referrer": "https://example.com/blog/some-article",
  "peer": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "local": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "tm_last_activity": "2026-01-15T09:30:00.000000Z",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_end": "2026-01-15T09:30:00.000000Z"
}

Changes

Changed in 7 of the 54 revisions of this API.138

  • d5569b3154112See the full diff
    • ●

      added the new web_session enum value to the local/type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new web_session enum value to the peer/type response property for the response status 200

      response-property-enum-value-added

  • 205d85b460a34See the full diff
    • ○

      added the new optional request property referrer

      new-optional-request-property

    • ○

      added the optional property local to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property peer to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property referrer to the response with the 200 status

      response-optional-property-added

  • 3591c4dad5072See the full diff
    • ○

      added the new optional request property page_url

      new-optional-request-property

    • ○

      added the optional property page_url to the response with the 200 status

      response-optional-property-added

  • d90e2d9717dc1See the full diff
    • ●

      removed the optional property welcome_message from the response with the 200 status

      response-optional-property-removed

  • 37603aee58ea1See the full diff
    • ○

      added the optional property welcome_message to the response with the 200 status

      response-optional-property-added

  • 39e5a5e6214c1See the full diff
    • ○

      endpoint added

      endpoint-added

  • 995c56ba92191See the full diff
    • ▲

      api path removed without deprecation

      api-path-removed-without-deprecation

    This revision also has 20 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog