> ## Documentation Index > Fetch the complete documentation index at: https://docs.vorel.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create a conversation > Pre-create a conversation from a CRM / webform handler before the customer messages. Closes the chicken-and-egg with `POST /api/v1/leads` (which requires an existing `conversation_id`). Strict-create: returns 409 if a conversation already exists for the (channel, customer_identifier) pair. Emits `conversation.created`. Internal ingest paths (WhatsApp inbound, voice, webform) do NOT yet emit this event — only the public-API write path does. ## OpenAPI ````yaml https://app.vorel.ai/api/v1/openapi.json post /api/v1/conversations openapi: 3.1.0 info: title: Vorel API version: 0.1.0 description: >- Public API for Vorel — the AI receptionist for any business. Read your conversations, leads, appointments, and catalog; push CRM-side updates back into the platform. All endpoints accept bearer-auth API keys issued at `/settings/integrations/api-keys` in the dashboard. Per-key rate limit is 200 req/min. contact: name: Vorel support email: hello@vorel.ai license: name: Proprietary servers: - url: https://app.vorel.ai description: Production - url: http://localhost:3000 description: Local dev security: - BearerAuth: [] tags: - name: Conversations description: Inbound customer conversations across channels. - name: Leads description: Qualified-lead rows attached to conversations. - name: Appointments description: Scheduled customer engagements. - name: Offerings description: Tenant catalog (properties, services, treatments — vertical-specific). - name: Analytics description: >- Aggregate metrics for tenant + automation consumers. The around-the-brain workflows read these rather than mass-querying the resource endpoints. - name: CRM description: >- Operator-side writes into the tenant's configured CRM (HubSpot / Salesforce / Zoho / etc.). Per-tenant field mappings translate canonical Vorel keys to vendor-side keys before the driver call. paths: /api/v1/conversations: post: tags: - Conversations summary: Create a conversation description: >- Pre-create a conversation from a CRM / webform handler before the customer messages. Closes the chicken-and-egg with `POST /api/v1/leads` (which requires an existing `conversation_id`). Strict-create: returns 409 if a conversation already exists for the (channel, customer_identifier) pair. Emits `conversation.created`. Internal ingest paths (WhatsApp inbound, voice, webform) do NOT yet emit this event — only the public-API write path does. operationId: createConversation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversationCreate' responses: '201': description: Conversation created. Emits `conversation.created`. content: application/json: schema: $ref: '#/components/schemas/Conversation' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '429': $ref: '#/components/responses/RateLimited' security: - BearerAuth: - conversations:write components: schemas: ConversationCreate: type: object required: - channel - customer_identifier description: >- Pre-create a conversation from a CRM / webform handler before the customer messages. Closes the chicken-and-egg with `POST /api/v1/leads` (which requires an existing `conversation_id`). Strict-create: returns 409 if a conversation already exists for the (channel, customer_identifier) pair under this tenant. properties: channel: type: string enum: - whatsapp - voice - webform - instagram - email description: >- Inbound channel slug. `whatsapp` / `voice` / `webform` are live; `instagram` / `email` are reserved slots for channels whose ingest paths land in a future phase. customer_identifier: type: string minLength: 1 maxLength: 255 description: >- Channel-native identifier — phone for WhatsApp/voice (E.164 strongly recommended; not enforced), email for webform, etc. customer_name: type: string maxLength: 200 nullable: true customer_language: type: string pattern: ^[a-z]{2}(-[A-Z]{2})?$ nullable: true description: >- ISO 639-1 (`en`, `ar`) or BCP 47 short tag (`en-US`). Other formats are rejected at the validation layer. Conversation: type: object required: - id - channel - customer_identifier - status - created_at properties: id: type: string format: uuid channel: type: string description: Inbound channel slug — e.g. `whatsapp`, `voice`, `webform`. customer_identifier: type: string description: >- Channel-native identifier — phone for WhatsApp/voice (E.164), email for webform, etc. customer_name: type: string nullable: true customer_language: type: string nullable: true description: ISO 639-1 (`en`, `ar`, …) when known. status: type: string description: Conversation lifecycle state — `active`, `closed`, … first_message_at: type: string format: date-time nullable: true last_message_at: type: string format: date-time nullable: true created_at: type: string format: date-time ErrorEnvelope: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - rate_limited - bad_request - not_found - conflict - internal_error description: Machine-readable error category. message: type: string description: >- Human-readable error description; safe to surface in tenant logs. responses: BadRequest: description: Body validation failed. Error message names the offending field. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Unauthorized: description: Missing, malformed, unknown, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: >- API key is valid but lacks the required scope for this endpoint. Issue a new key with the necessary scope at `/settings/integrations/api-keys`. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Conflict: description: >- Resource already exists with a conflicting unique field. Emitted by `POST /api/v1/leads` when the conversation already has a lead, and by `POST /api/v1/conversations` when a conversation already exists for the (channel, customer_identifier) pair under your tenant. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: >- 200 req/min per API key exceeded. `Retry-After` header carries seconds-until-reset. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer description: Unix epoch seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: vapk__<48-hex> description: >- Tenant-issued API key. Format: `vapk_live_<48 hex chars>` (60 chars total). Issue + manage at `/settings/integrations/api-keys` in the Vorel dashboard. Each key has a scope set (`read`, `leads:write`, `appointments:write`, `offerings:write`); endpoints requiring a write scope reject keys without it with a 403 envelope. ````