Custom Digital Channel — Integration Guide

Overview

The Custom Digital Channel lets your platform deliver customer turns to Salted CX. Direction is defined from your point of view:

• Trigger (inbound, you → us) — a message the customer already sent in your widget. You push it to us.

• Action (outbound, us → you) — asking your platform to render a reply. This is a future capability and is not part of this guide.

Each trigger runs through the same conversation lifecycle as a native digital turn (translation, routing to an agent or bot).

Authentication

All requests use your per-account bearer token (the same token used for the YourLogic integration):

Authorization: Bearer <your-account-token>
Content-Type: application/json

Requests without a valid token for the account in the path are rejected.

Flow

sequenceDiagram
	autonumber
	participant You as Your platform
	participant CreateApi as Create-conversation endpoint
	participant API as Triggers endpoint
	You->>CreateApi: create conversation
	CreateApi-->>You: conversationPid
	You->>API: push triggers on conversationPid
	API-->>You: per-trigger result

Create the conversation once (you receive a conversationPid), then push one or more triggers to that conversation.

Create the conversation

Create the conversation first; the response returns a conversationId that you use as conversationPid when pushing triggers. The contact is created or matched automatically from the customer block — you do not make a separate contact call.

POST /api/v1/live/custom-channel/accounts/{accountId}/conversations

The conversation is created as an inbound chat conversation. Request body:

{
  "brandPid": "<brand-uuid>",
  "customer": {
    "displayName": "Jane Doe",
    "contact": { "contact": "[email protected]", "contactType": "Anonymous" }
  },
  "languageCustomer": "en",
  "url": "https://widget.example.com/chat",
  "custom": null
}

Request fields:

customer fields:

Response:

{ "conversationId": "11111111-2222-3333-4444-555555555555" }

Push triggers

POST /api/v1/live/custom-channel/accounts/{accountId}/conversations/{conversationPid}/triggers

The body is an ordered array of triggers. v1 supports participantType = CUSTOMER and two trigger types: MESSAGE and ANSWER.

Common fields

MESSAGE — a customer text message

Attachment object:

ANSWER — a customer answering a question

Examples

Text message:

{
  "triggers": [
    {
      "type": "MESSAGE",
      "participantType": "CUSTOMER",
      "externalId": "a1b2c3-0001",
      "content": "Hello, I need help with my order"
    }
  ]
}

Message with an attachment:

{
  "triggers": [
    {
      "type": "MESSAGE",
      "participantType": "CUSTOMER",
      "externalId": "a1b2c3-0002",
      "content": "Here is the photo",
      "attachments": [
        { "name": "receipt.jpg", "body": "<base64-bytes>", "mimeType": "image/jpeg" }
      ]
    }
  ]
}

Answer to a question:

{
  "triggers": [
    {
      "type": "ANSWER",
      "participantType": "CUSTOMER",
      "externalId": "a1b2c3-0003",
      "answerId": "yes",
      "responseToId": "11111111-2222-3333-4444-555555555555"
    }
  ]
}

Response

The response reports a status per trigger, in the same order:

{
  "conversationPid": "11111111-2222-3333-4444-555555555555",
  "results": [
    { "index": 0, "type": "MESSAGE", "status": "CREATED", "message": "Created" }
  ]
}

Per-trigger status:

HTTP status codes:

Idempotency

Each trigger carries an externalId that you choose. Re-sending a trigger with the same externalId does not create a second turn — it returns DUPLICATE. Use stable ids so safe retries never duplicate messages.

Batch semantics

• Triggers are applied strictly in order.

• On the first failure, processing stops; remaining triggers are returned as SKIPPED and the HTTP status is 207.

• Send a single trigger per request if you prefer to handle each independently.