Quickstart

This walkthrough gets you from a fresh API key to your first conversation in a few calls. First create a key (see Authentication) and export it:

export CONVOT_TOKEN="ck_xxxxxxxxxxxxxxxx:secret"

1. List conversations

curl https://app.convot.io/v1/conversations \
  -H "Authorization: Bearer $CONVOT_TOKEN"

{
  "conversations": [
    { "id": "9b1f...", "status": "open", "contact_id": 88, "messages_count": 3 }
  ],
  "meta": { "page": 1, "per_page": 30, "has_more": false }
}

The id is the conversation’s UUID. Use it for message and status calls.

2. Create or update a contact

Contacts are found-or-created by email (or external_id), so this is safe to call repeatedly:

curl -X POST https://app.convot.io/v1/contacts \
  -H "Authorization: Bearer $CONVOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "Jane Doe", "custom_data": { "plan": "pro" } }'

3. Start a conversation

Open a conversation for that contact and seed the first message:

curl -X POST https://app.convot.io/v1/conversations \
  -H "Authorization: Bearer $CONVOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "content": "Hi Jane, following up on your order." }'

4. Reply on an existing conversation

curl -X POST https://app.convot.io/v1/conversations/9b1f.../messages \
  -H "Authorization: Bearer $CONVOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Your refund is on the way." }'

To send as a specific teammate instead of the app’s API identity, add "operator_id": 42 with a real user id from your app.

5. List messages on a conversation

curl https://app.convot.io/v1/conversations/9b1f.../messages \
  -H "Authorization: Bearer $CONVOT_TOKEN"

Every message carries a type: incoming and outgoing are customer-facing, while note (internal private notes) and activity (system events like resolve or reopen) are your team’s internal records. By default all types are returned. To fetch only the customer-facing thread, filter with type:

curl "https://app.convot.io/v1/conversations/9b1f.../messages?type=incoming,outgoing" \
  -H "Authorization: Bearer $CONVOT_TOKEN"

Where to go next

The full reference documents every endpoint, parameter, and response. Pair it with Scopes, Rate limits, and Errors.