Identified visitors (save-visitor)

Link chat to users in your own database.

Anonymous visitors need no backend work. When a user is logged into your product, call save-visitor from your server, store the returned chatVisitorId in your database, and pass it when the widget loads.

Upsert visitor (server-side)

curl -X POST https://platform.sohojx.com/api/chat/applications/cap_YOUR_APP_ID/save-visitor \
  -H "Authorization: Bearer YOUR_CHAT_APPLICATION_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_42",
    "name": "Rahim",
    "email": "rahim@example.com",
    "phone": "+880...",
    "avatarUrl": "https://example.com/avatar.jpg",
    "customFields": { "company": "ACME", "plan": "pro" }
  }'

Response includes chatVisitorId (cv_...). Upsert is keyed by chatApplicationId + externalUserId. Custom field keys must match pre-chat field definitions configured for that application.

Do not call save-visitor from the browser. The widget key alone cannot authenticate this endpoint.

Open widget for that user

After save-visitor, resume the same visitor on return visits by passing chatVisitorId into the session API (the embed handles this when you configure identified mode from your integration layer).