Initialize Chat Contact

Create or initialize a new chat contact. This is typically used when a visitor starts a chat.

POST https://developers.chatway.app/api/v1/contacts/initialize

Example request

curl -X POST "https://developers.chatway.app/api/v1/contacts/initialize" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "widgetId": "eouqtiupanm6uvglwshy",
    "browser_type": "browser type",
    "operating_system": "operating system",
    "ip": "ip",
    "is_simulator": true,
    "language": "language",
    "name": "John Doe",
    "timezone": "timezone",
    "location": "location",
    "country": "country",
    "country_dialing_code": "country dialing code",
    "email": "[email protected]",
    "preferred_chat_language": "auto-detect",
    "phone": "+1XXXXXXXXXX",
    "marketplace_channel": "marketplace channel",
    "marketplace_origin": "marketplace origin",
    "is_form_auto_submitted": true,
    "message": {
        "urls": [
            "https://example.com/page"
        ],
        "content": "Hello world"
    },
    "page_visited": [
        {
            "page": "page",
            "date": "2026-02-04T10:30:00Z"
        }
    ]
}'

Request body

application/json

• widgetId (string, required) — Widget identifier
• browser_type (string|null)
• operating_system (string|null)
• ip (string|null)
• is_simulator (boolean|null)
• language (string|null)
• name (string|null)
• timezone (string|null)
• location (string|null)
• country (string|null)
• country_dialing_code (string|null)
• email (string|null (email))
• preferred_chat_language (string|null enum: auto-detect, en, pt, es, de, fr, ja, ru, da, fi, it, tr, zh, ab, ace, ach, af, sq, alz, am, ar, hy, as, awa, ay, az, ban, bm, ba, eu, btx, bts, bbc, be, bem, bn, bew, bho, bik, bs, br, bg, bua, yue, ca, ceb, ny, zh-TW, cv, co, crh, hr, cs, din, dv, doi, dov, nl, dz, eo, et, ee, fj, fil, fr-FR, fr-CA, fy, ff, gaa, gl, ka, el, gn, gu, gv, ht, cnh, ha, haw, he, iw, hi, hmn, hu, hrx, is, ig, ilo, id, ga, jv, jw, kn, pam, kk, km, cgg, rw, ktu, gom, ko, kri, ku, ckb, ky, lo, ltg, la, lv, lij, li, ln, lt, lmo, luo, lb, lg, mk, mai, mak, mg, ms, ms-Arab, ml, mt, mi, mr, mni-Mtei, min, lus, mn, my, nr, new, ne, no, nus, oc, or, om, pag, pap, ps, fa, pl, pt-PT, pt-BR, pa, qu, rom, ro, rn, sm, sg, sa, gd, nso, sr, st, crs, shn, sn, scn, szl, sd, si, sk, sl, so, su, sw, ss, sv, tl, tg, ta, tt, te, tet, th, ti, ts, tn, tk, ak, uk, ur, ug, uz, vi, cy, xh, yi, yo, yua, zu, zh-CN, ak, gom, null)
• phone (string|null)
• marketplace_channel (string|null)
• marketplace_origin (string|null)
• is_form_auto_submitted (boolean|null)
• message (object) — Optional pre-chat message with referenced page URLs (each URL must be valid)
• page_visited (array|null)

Responses

200

application/json

• message (string, required)
• data (object, required)
  • type (string, required)
  • id (string, required)
  • attributes (object, required)
    • widget_name (string|null, required)
    • widget_id (string|null, required)
    • team_id (string|null, required)
    • name (string|null, required)
    • email (string|null, required)
    • phone (string|null, required)
    • country_dialing_code (string|null, required)
    • bgcolor (string|null, required)
    • location (string|null, required)
    • browser_type (string|null, required)
    • country_code (string|null, required)
    • country (string|null, required)
    • country_flag (string|null, required)
    • country_emoji (string|null, required)
    • page_visited (array, required)
    • timezone (string|null, required)
    • language (string|null, required)
    • ip (string|null, required)
    • operating_system (string|null, required)
    • online_status (string|null, required)
    • last_active_at (string|null, required)
    • blocked_at (string|null, required)
    • is_name_updated (boolean, required)
    • created_at (string|null, required)
    • verified_id (string|null, required)
    • verified_email (string|null, required)

422

Examples

Request body example

{
    "widgetId": "eouqtiupanm6uvglwshy",
    "browser_type": "browser type",
    "operating_system": "operating system",
    "ip": "ip",
    "is_simulator": true,
    "language": "language",
    "name": "John Doe",
    "timezone": "timezone",
    "location": "location",
    "country": "country",
    "country_dialing_code": "country dialing code",
    "email": "[email protected]",
    "preferred_chat_language": "auto-detect",
    "phone": "+1XXXXXXXXXX",
    "marketplace_channel": "marketplace channel",
    "marketplace_origin": "marketplace origin",
    "is_form_auto_submitted": true,
    "message": {
        "urls": [
            "https://example.com/page"
        ],
        "content": "Hello world"
    },
    "page_visited": [
        {
            "page": "page",
            "date": "2026-02-04T10:30:00Z"
        }
    ]
}

Response 200 example

{
    "message": "Conversation not found",
    "data": {
        "type": "chat-contacts",
        "id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
        "attributes": {
            "widget_name": "Main site widget",
            "widget_id": "eouqtiupanm6uvglwshy",
            "team_id": "MOCK_TEAM_ID",
            "name": "John Doe",
            "email": "[email protected]",
            "phone": "+1XXXXXXXXXX",
            "country_dialing_code": "+1",
            "bgcolor": "#007F3E",
            "location": "New York, US",
            "browser_type": "Chrome 143",
            "country_code": "US",
            "country": "United States",
            "country_flag": "country flag",
            "country_emoji": "country emoji",
            "page_visited": [],
            "timezone": "timezone",
            "language": "language",
            "ip": "ip",
            "operating_system": "operating system",
            "online_status": "online",
            "last_active_at": "2026-02-04T10:30:00Z",
            "blocked_at": "blocked at",
            "is_name_updated": false,
            "created_at": "2026-02-04T10:30:00Z",
            "verified_id": "verified id",
            "verified_email": "verified email"
        }
    }
}