Initialize Chat Contact

Initialize a visitor contact for a widget. Obtain the widget identifier from data[].id in List Widgets and send it as widgetId. The response returns the contact under data; save data.id for later contact operations.

Start with the required widgetId field. The other fields add optional visitor details or context; you do not need to copy every field from the example to initialize a contact. Supply only information your integration has and needs.

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"
}'

Request body

application/json

• widgetId (string, required) — Widget identifier
• browser_type (string|null)
• operating_system (string|null)
• ip (string|null)
• is_simulator (boolean|null) — Optional boolean used by the Chatway widget. This endpoint validates it but does not store it, so it has no effect on the created contact. Omit it.
• 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) — Optional boolean used by the Chatway widget. This endpoint validates it but does not store it, so it has no effect on the created contact. Omit it.
• form_submitted (boolean|null)
• message (object) — Optional pre-chat message with referenced page URLs (each URL must be valid)
• page_visited (array|null)

Responses

201

To send a visitor message for the returned contact, call Create Visitor Message with the same widget, the returned ID as contact_id, and your message in content. That endpoint uses widget_id, while this endpoint uses widgetId. Keep this spelling difference when building requests.

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

404

The widget does not exist or does not belong to your team.

application/json

• message (string, required)

Examples

Request body example

{
    "widgetId": "eouqtiupanm6uvglwshy"
}

Response 201 example

{
    "message": "Contact created.",
    "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": "Green #88170",
            "email": null,
            "phone": null,
            "country_dialing_code": null,
            "bgcolor": "#007F3E",
            "location": null,
            "browser_type": null,
            "country_code": null,
            "country": null,
            "country_flag": null,
            "country_emoji": null,
            "page_visited": [],
            "timezone": null,
            "language": null,
            "ip": null,
            "operating_system": null,
            "online_status": null,
            "last_active_at": null,
            "blocked_at": null,
            "is_name_updated": false,
            "created_at": "2026-02-04T10:30:00Z",
            "verified_id": "",
            "verified_email": ""
        }
    }
}