---
title: "Create Visitor Message"
method: POST
path: "/conversations"
tags: ["Messages"]
---

# Create Visitor Message

`POST /conversations`

## Request

- Base URL: `https://developers.chatway.app/api/v1`
- URL: `https://developers.chatway.app/api/v1/conversations`
- Auth: API key in header `X-API-KEY`

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.

## Request body

- object
  - `widget_id` string, required: Required. Identifier of the widget the visitor writes through. It must belong to your team.
  - `contact_id` string, nullable: 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, nullable: Optional. Saved only when a new contact is created.
  - `email` string, email, nullable: 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, nullable: 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.

## Response `200`

- union
  - object
    - `data` object, required
      - `type` string, required
      - `id` string, required
      - `attributes` object, required
        - `conversation_id` string, required
        - `chat_contact_id` string, nullable, required
        - `agent` object, nullable, required
          - `id` string, nullable, required
          - `name` string, nullable, required
        - `contact` object, nullable, required
          - `id` string, nullable, required
          - `name` string, nullable, required
          - `email` string, nullable, required
          - `phone` string, nullable, required
        - `origin` string, required
        - `content` string, required
        - `type` string, required
        - `created_at` string, nullable, required
  - object

## Other responses

- `404`: The widget does not exist or does not belong to your team.
- `422`: Validation error

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)