> ## 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 > Sends a first message to a contact from one of your channels, and opens the conversation (or continues the existing one). On WhatsApp, outside the 24h window opened by the contact, only an approved template can be sent (GET /templates). The AI agent keeps answering the contact unless `handover` is true. ## OpenAPI ````yaml /api-reference/v2.0/openapi.json post /conversations openapi: 3.1.0 info: title: Shortext API description: >- **Versioning**: every version is a frozen contract. A released version only receives additive changes (new endpoints, new optional fields, new response fields); anything breaking ships in a new version. Responses carry `X-Shortext-Api-Version`. When a version is scheduled for removal, responses also carry `Deprecation` and `Sunset` headers; after the sunset date the version answers HTTP 410. The list of versions and their status is available at `GET /api/versions`. **Responses**: always HTTP 200. Check `success` and `code` (`1000` = success), see `ApiEnvelope`. On failure, `trace_id` identifies the request for support. version: '2.0' servers: - url: https://shortext.ny-corp.io/api/v2.0 security: [] tags: - name: Agents description: Agents - name: Channels description: Channels - name: Conversations description: Conversations - name: Account description: Account - name: Templates description: Templates - name: Hosted sessions description: Hosted sessions - name: Webhooks description: Webhooks paths: /conversations: post: tags: - Conversations summary: Start a conversation description: >- Sends a first message to a contact from one of your channels, and opens the conversation (or continues the existing one). On WhatsApp, outside the 24h window opened by the contact, only an approved template can be sent (GET /templates). The AI agent keeps answering the contact unless `handover` is true. operationId: startConversation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartConversationInput' responses: '200': description: >- Always HTTP 200: the outcome is in `success` and `code` (absolute value of the response code). content: application/json: schema: allOf: - $ref: '#/components/schemas/ApiEnvelope' - properties: body: properties: conversation: $ref: '#/components/schemas/Conversation' message: $ref: '#/components/schemas/Message' type: object type: object security: - bearerAuth: [] components: schemas: StartConversationInput: required: - channel - channel_id - contact - message properties: channel: type: string enum: - whatsapp - mail - shortext channel_id: description: >- Your channel id (`GET /channels`): WhatsApp phone id, mailbox id (mbx_...) or Shortext endpoint id (ste_...) type: string contact: properties: identifier: description: Phone (E.164 without +), email or your own id for Shortext type: string profile: properties: lastname: type: string firstname: type: string email: type: string preferred_language: type: string enum: - en - fr - es - de type: object type: object message: $ref: '#/components/schemas/MessageInput' handover: description: >- true: a human follows the conversation, the AI agent does not answer the contact type: boolean default: false type: object ApiEnvelope: properties: success: type: boolean example: true code: type: integer example: 1000 message: type: string example: Request success. body: description: Endpoint payload, null when there is none token: description: Present only on authentication routes type: - string - 'null' trace_id: description: Present only when success is false type: - string - 'null' type: object Conversation: properties: id: description: The conversation_id of the webhooks type: string status: description: '`active`: a session is open; `archived`: replying opens a new one' type: string enum: - active - archived channel: properties: type: type: string enum: - whatsapp - mail - shortext id: description: The channel_id of the webhooks type: string type: object agent: description: Agent answering on the channel; null when the channel is detached properties: id: type: string name: type: string type: - object - 'null' contact: properties: identifier: type: string identifier_type: type: string profile: type: object country: type: object type: object session: description: Current session; null when archived properties: started_at: type: string format: date-time ends_at: type: - string - 'null' format: date-time handover: description: 'A human took over: the AI agent does not answer' type: boolean handover_at: type: - string - 'null' format: date-time assignee: oneOf: - $ref: '#/components/schemas/Member' - type: 'null' type: - object - 'null' last_message_at: type: - string - 'null' format: date-time created_at: type: string format: date-time type: object Message: properties: id: description: >- Public representation of a message (API v2.0): exactly the data of the message.* webhooks. type: string example: msg.XXXXX conversation_id: type: string direction: type: string enum: - inbound - outbound channel: type: string enum: - whatsapp - mail - shortext channel_id: type: string contact: type: object message: properties: id: description: Id on the channel (your own id for Shortext) type: - string - 'null' type: type: string example: text content: type: object example: text: Hello type: object status: type: string created_at: type: string format: date-time type: object MessageInput: description: Grammar of a message, the same on every endpoint and version required: - type - content properties: type: type: string enum: - text - template - interactive - media content: description: >- `text`: `{ text }`. `template`: `{ template_name, language, body?, header?, buttons?, category? }`. `interactive`: `{ type, body, action, header?, footer? }`. `media`: `{ media_type, media_url, caption?, filename?, mime? }` (media_type: image, video, document, audio) type: object example: text: Hello, how can I help? type: object Member: description: User of the company (dashboard, mobile app) properties: id: type: string example: USR-XXXXX name: type: string type: object securitySchemes: bearerAuth: type: http description: >- Company API key, sent as `Authorization: Bearer `. Create it in the dashboard (Developer > API Keys) with the permissions the integration needs. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.