Create Visitor Message

Send a message as a visitor through a widget. Chatway picks the contact and the conversation for you, so no conversation_id is needed.

How the contact is selected

If contact_id matches an existing contact on this widget, it takes priority and the supplied name, email and phone are ignored. If contact_id is missing or not found, Chatway looks up the contact by email, then creates a new contact if no match exists. An unknown contact_id does not itself cause an error.

In detail, Chatway checks these in order and uses the first match:

1. contact_id: the existing contact with this ID, if it belongs to the widget in widget_id. It always takes priority over email.
2. email: the most recent contact on the widget with this email. This is also used when contact_id is sent but not found on the widget.
3. New contact: if nothing matches, or neither contact_id nor email is sent, a new contact is created from name, email and phone. It gets a new ID; an unknown contact_id is never reused as the ID.

When an existing contact is matched, name, email and phone are not used to update it.

Which conversation receives the message

• Contact has a conversation: the message is added to the contact's most recent conversation. If that conversation is resolved, it is reopened automatically.
• Contact has no conversation (including every new contact): a new conversation is started with this message.

Reusing an initialized contact

If you created the contact with POST /api/v1/contacts/initialize, send the returned contact ID as contact_id with the same widget. The message then goes to that contact instead of creating another one.

Note: this endpoint uses widget_id, while the initialize endpoint uses widgetId. The message text goes in the top-level content field.

Examples

• Existing contact: send widget_id, contact_id and content.
• Find by email: send widget_id, email and content. Add name and phone so they are saved if a new contact has to be created.
• Anonymous visitor: send only widget_id and content. A new contact and conversation are created every time.

Use data.attributes.contact.id from the response as contact_id to send more messages as the same visitor.

POST https://developers.chatway.app/api/v1/conversations

Example request

curl -X POST "https://developers.chatway.app/api/v1/conversations" \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_id": "eouqtiupanm6uvglwshy",
    "contact_id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "content": "Hi, I need help with my order."
}'

Request body

application/json

• widget_id (string, required) — Required. Identifier of the widget the visitor writes through. It must belong to your team.
• contact_id (string|null) — Optional. ID of an existing contact on this widget. When it matches, it takes priority and `name`, `email` and `phone` are ignored. If it is not found on the widget, no error is returned: Chatway falls back to `email`, then creates a new contact with a new ID.
• name (string|null) — Optional. Saved only when a new contact is created.
• email (string|null (email)) — Optional. Used to find an existing contact on this widget when `contact_id` is not sent or not found. Saved when a new contact is created.
• phone (string|null) — Optional. Saved only when a new contact is created. 7 to 15 digits with an optional leading `+`; no spaces, dashes or brackets.
• content (string, required) — Required. The visitor's message text.

Responses

200

application/json

• data (object, required)
  • type (string, required)
  • id (string, required)
  • attributes (object, required)
    • conversation_id (string, required)
    • chat_contact_id (string|null, required)
    • agent (object|null, required)
      • id (string|null, required)
      • name (string|null, required)
    • contact (object|null, required)
      • id (string|null, required)
      • name (string|null, required)
      • email (string|null, required)
      • phone (string|null, required)
    • origin (string, required)
    • content (string, required)
    • type (string, required)
    • created_at (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

{
    "widget_id": "eouqtiupanm6uvglwshy",
    "contact_id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
    "name": "Jane Doe",
    "email": "[email protected]",
    "phone": "+15551234567",
    "content": "Hi, I need help with my order."
}

Response 200 example

{
    "data": {
        "type": "messages",
        "id": "msg-1",
        "attributes": {
            "conversation_id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
            "chat_contact_id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
            "agent": null,
            "contact": {
                "id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
                "name": "John Doe"
            },
            "origin": "chat",
            "content": "Hello, I need help",
            "type": "message",
            "created_at": "2026-02-04T10:30:00Z"
        }
    }
}