POST
Create EXTERNAL Conversation (API Key)

Overview

Create an EXTERNAL conversation using API keys only—no dashboard login. Use this from your backend (e.g. Node, Laravel, Django) when integrating Vocantly into your app. Same credentials you use for Issue SDK Token: X-Api-Key and X-Api-Secret.
Backend-only. Store App ID, public key, and secret key on your server. Call this endpoint when a business event occurs (e.g. order placed, appointment booked). Then call Issue SDK Token for each participant and return token + conversation_id to your frontend.

When to Use This Endpoint

  • You are building a backend that integrates Vocantly (SDK, external chat).
  • You want to create conversations without using dashboard login (JWT).
  • You already have an App and its public key + secret key from the dashboard.
For dashboard flows (internal users, DIRECT/GROUP/SUPPORT), use Create Conversation with JWT instead.

Request Headers

No appId in the request. The backend finds the app by X-Api-Key (public key) and verifies X-Api-Secret. Use the same keys you use for Issue SDK Token (where appId is in the URL: POST /apps/:appId/tokens). For this endpoint, the app is implied by the headers.

Request Body

string
required
Your app’s ID for this conversation (e.g. order ID, appointment ID, or sorted pair of user IDs). Must be unique per tenant. Idempotent: same external_id returns the existing conversation.
array
required
At least 2 participants. Each object: external_user_id (required), name, email, role (optional). external_user_id must match the ID you pass when issuing SDK tokens for that user.

Example Request

Response

Same shape as Create Conversation: success, message, data with id, type, external_id, etc.

Success (201)

If a conversation with the same external_id already exists, the API returns that conversation (idempotent).

Error Responses

Backend Integration Flow

  1. Create conversation (this endpoint) when your business event occurs (e.g. “Start chat” clicked, order placed).
  2. Issue SDK token for the current user: POST /apps/:appId/tokens with same API keys and external_user_id matching a participant.
  3. Return { token, conversation_id: data.id } to your frontend.
  4. Frontend uses SDK with token, connects, joins conversation_id, and sends/receives messages.

List EXTERNAL conversations

Inbox for external user

Get EXTERNAL messages

Message history

Issue SDK Token

Issue token for participants

SDK Installation

Use token in frontend

Conversations Guide

EXTERNAL conversations overview

Create Conversation (JWT)

Dashboard / other types