Open a widget conversation from your CRM

Add a Message in Evercom action to your CRM or admin panel. Your server asks Evercom to find or create the customer's widget conversation, then redirects the employee to the returned Evercom URL. The employee writes the first message in Evercom.

The API call itself does not send a message or notify the customer.

Before you start

• Create a workspace access token. Keep it on your server and never expose it in browser code.
• Use a stable customer ID from your system as external_id.
• Configure the widget to identify the same customer ID. If widget verification is enabled, follow User identification and verification.

The workspace access token authenticates your server to the Public API. The widget user_token is a different credential: it verifies the signed-in customer in the browser.

Open or create the conversation

Call POST https://api.evercom.app/v1/conversations from your server. The inline contact form lets one request find or create both the contact and the conversation:

curl --request POST 'https://api.evercom.app/v1/conversations' \
  --header 'Authorization: Bearer YOUR_WORKSPACE_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: crm-message-customer-00123' \
  --data '{
    "channel": "widget",
    "contact": {
      "external_id": "customer-00123",
      "name": "Ava Customer",
      "email": "ava@example.com",
      "locale": "en"
    }
  }'

Evercom returns 201 Created when it creates the conversation and 200 OK when it reuses an eligible existing conversation. A response contains:

{
  "workspace_id": 42,
  "contact_id": 123,
  "contact_created": false,
  "conversation_id": 456,
  "conversation_created": true,
  "conversation_status": "open",
  "conversation_url": "https://app.evercom.app/conversations/456?workspace_id=42"
}

Redirect the employee's browser to conversation_url. Evercom checks that the employee belongs to the URL's workspace before loading the conversation.

If your system already stores the Evercom contact ID, send contact_id instead:

{
  "channel": "widget",
  "contact_id": 123
}

Use exactly one of contact or contact_id.

Contact profile behavior

The inline name, email, and locale values are used only when Evercom creates the contact. If external_id already exists, this operation returns that contact without overwriting its profile.

Use POST /v1/contacts separately only when your integration needs to create or resolve a contact without opening a conversation. You do not need to call it before POST /v1/conversations.

External IDs are exact and case-sensitive. Leading zeroes are significant, so 00123, 123, and Customer-123 identify different customers.

Safe retries

Give each logical request an Idempotency-Key. If a timeout leaves the result uncertain, retry the same method, URL, key, and JSON body. Evercom reproduces the original result for at least 24 hours and returns the precise expiry in the Idempotency-Key-Expires-At response header.

Do not reuse a key with a different body. Evercom rejects that with 409 Conflict. If another copy of the same request is still running, Evercom also returns 409 with a Retry-After header.

What the customer sees

An empty API-created conversation is hidden in the customer widget. It appears when the employee sends the first public message in Evercom. Normal widget realtime delivery and configured offline email notifications then apply.

Blocked contacts cannot be opened through this endpoint. The API returns 403 Forbidden without creating a conversation.