> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shortext.ny-corp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a conversation and reply

> Write first to a contact, reply in an existing conversation, and respect the WhatsApp 24-hour rule.

Requires a key with **Send messages**.

## Write first to a contact

`POST /conversations` sends a first message from one of your channels and opens the conversation (or continues the existing one with this contact).

| Field | Description |
| - | - |
| `channel` | `whatsapp`, `mail` or `shortext`. |
| `channel_id` | Your channel, from `GET /channels`. |
| `contact` | Who you write to, see [Contact format](https://docs.shortext.ny-corp.io/api-reference/contact-format.md). |
| `message` | What you send, see [Message format](https://docs.shortext.ny-corp.io/api-reference/message-format.md). |
| `handover` | `true` if a human follows the conversation: the AI agent will not answer the contact. Default `false`: the agent answers the replies. |

```bash cURL theme={null}
curl -X POST https://shortext.ny-corp.io/api/v2.0/conversations \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "channel_id": "532867649916076",
    "contact": {
      "identifier": "237699999999",
      "profile": { "firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr" }
    },
    "message": {
      "type": "template",
      "content": {
        "template_name": "order_update",
        "language": "fr",
        "body": { "name": "Brice", "order": "A-1042" }
      }
    }
  }'
```

```php PHP theme={null}
<?php
$response = (new GuzzleHttp\Client())->post('https://shortext.ny-corp.io/api/v2.0/conversations', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'),
        'Accept'        => 'application/json',
    ],
    'json' => [
        'channel'    => 'whatsapp',
        'channel_id' => '532867649916076',
        'contact'    => [
            'identifier' => '237699999999',
            'profile'    => ['firstname' => 'Brice', 'lastname' => 'Mbarga', 'preferred_language' => 'fr'],
        ],
        'message'    => [
            'type'    => 'template',
            'content' => [
                'template_name' => 'order_update',
                'language'      => 'fr',
                'body'          => ['name' => 'Brice', 'order' => 'A-1042'],
            ],
        ],
    ],
]);

$result = json_decode((string) $response->getBody(), true);
if (!$result['success']) {
    throw new RuntimeException("Shortext error {$result['code']}: {$result['message']}");
}
$conversationId = $result['body']['conversation']['id'];
```

```javascript Node.js theme={null}
const response = await fetch("https://shortext.ny-corp.io/api/v2.0/conversations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel: "whatsapp",
    channel_id: "532867649916076",
    contact: {
      identifier: "237699999999",
      profile: { firstname: "Brice", lastname: "Mbarga", preferred_language: "fr" },
    },
    message: {
      type: "template",
      content: {
        template_name: "order_update",
        language: "fr",
        body: { name: "Brice", order: "A-1042" },
      },
    },
  }),
});

const result = await response.json();
if (!result.success) {
  throw new Error(`Shortext error ${result.code}: ${result.message}`);
}
const conversationId = result.body.conversation.id;
```

```python Python theme={null}
import os
import requests

response = requests.post(
    "https://shortext.ny-corp.io/api/v2.0/conversations",
    headers={
        "Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}",
        "Accept": "application/json",
    },
    json={
        "channel": "whatsapp",
        "channel_id": "532867649916076",
        "contact": {
            "identifier": "237699999999",
            "profile": {"firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr"},
        },
        "message": {
            "type": "template",
            "content": {
                "template_name": "order_update",
                "language": "fr",
                "body": {"name": "Brice", "order": "A-1042"},
            },
        },
    },
)

result = response.json()
if not result["success"]:
    raise RuntimeError(f"Shortext error {result['code']}: {result['message']}")
conversation_id = result["body"]["conversation"]["id"]
```

The response `body` holds `conversation` and `message`.

## The WhatsApp 24-hour rule

WhatsApp only accepts free-form messages (text, media, interactive) within **24 hours after the contact's last message**. Outside that window, and to write first, you must send an approved **template**.

| Endpoint | Outside the 24-hour window |
| - | - |
| `POST /conversations` with a non-template message | Refused with `1002`: "Outside the 24h window opened by the contact, WhatsApp only accepts an approved template". |
| `POST /conversations` with a template | Sent. |
| `POST /conversations/{id}/messages` (reply) | A free-form reply is sent as a notification template, so it reaches the contact. |

Mailboxes and Shortext endpoints have no such window.

> [!TIP]
>
> To decide in advance, look at the conversation's last inbound message (`GET /conversations/{id}/messages`) or keep the time of the last `message.received` webhook.

## Reply in a conversation

`POST /conversations/{id}/messages` with a `message`:

```bash cURL theme={null}
curl -X POST https://shortext.ny-corp.io/api/v2.0/conversations/$CONVERSATION_ID/messages \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "message": { "type": "text", "content": { "text": "Your order A-1042 has left our warehouse." } },
    "handover": false
  }'
```

```php PHP theme={null}
<?php
$response = (new GuzzleHttp\Client())->post("https://shortext.ny-corp.io/api/v2.0/conversations/{$conversationId}/messages", [
    'headers' => ['Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json'],
    'json'    => [
        'message'  => ['type' => 'text', 'content' => ['text' => 'Your order A-1042 has left our warehouse.']],
        'handover' => false,
    ],
]);
$result = json_decode((string) $response->getBody(), true);
```

```javascript Node.js theme={null}
const response = await fetch(`https://shortext.ny-corp.io/api/v2.0/conversations/${conversationId}/messages`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    message: { type: "text", content: { text: "Your order A-1042 has left our warehouse." } },
    handover: false,
  }),
});
const result = await response.json();
```

```python Python theme={null}
response = requests.post(
    f"https://shortext.ny-corp.io/api/v2.0/conversations/{conversation_id}/messages",
    headers={"Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json"},
    json={
        "message": {"type": "text", "content": {"text": "Your order A-1042 has left our warehouse."}},
        "handover": False,
    },
)
result = response.json()
```

By default a reply **takes the conversation over** (`handover: true`), as when a person answers in the Inbox: the AI agent stops answering. Send `"handover": false` for automatic notifications that should not stop the agent.

## Find a conversation

`GET /conversations` filters by `contact` (phone, email or your own id), `channel` and `channel_id`, `agent_id`, `status` (`active`, `archived`), `assignee`, `ticket_id` and `updated_since`. For example:

```bash theme={null}
curl "https://shortext.ny-corp.io/api/v2.0/conversations?channel=whatsapp&contact=237699999999" \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" -H "Accept: application/json"
```

Reading conversations requires **View messages**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.