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

# Start conversation

> Requires `conversations:start`. WhatsApp only. Requires approved prepared template and recipient consent; respects opt-outs. Reuse Idempotency-Key with identical input only. Keys are scoped to the tenant and target conversation. Use requestEventId with message-request status to reconcile.



## OpenAPI

````yaml /openapi.json post /conversations/start
openapi: 3.0.3
info:
  title: Visito M2M API
  version: 1.0.0
  description: >-
    Tenant-scoped server-to-server API for channels, conversations, commerce,
    custom AI tools, and WhatsApp templates. Send operations are asynchronous
    and return queued acknowledgements. Expansion adds conversation controls,
    knowledge, sales opportunities, delivery status, reporting, and signed
    webhooks.
servers:
  - url: https://platform-api.visitoai.com/m2m/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Channels
  - name: Conversations
  - name: Commerce
  - name: Custom tools
  - name: WhatsApp templates
  - name: Properties
  - name: Knowledge
  - name: Sales CRM
  - name: Delivery
  - name: Reporting
  - name: Webhooks
paths:
  /conversations/start:
    post:
      summary: Start conversation
      description: >-
        Requires `conversations:start`. WhatsApp only. Requires approved
        prepared template and recipient consent; respects opt-outs. Reuse
        Idempotency-Key with identical input only. Keys are scoped to the tenant
        and target conversation. Use requestEventId with message-request status
        to reconcile.
      operationId: start_conversation
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            maxLength: 200
            minLength: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                channel:
                  type: string
                  enum:
                    - whatsapp
                targetChannelId:
                  type: string
                  maxLength: 120
                  minLength: 1
                phoneNumber:
                  type: string
                  maxLength: 32
                  minLength: 8
                contactName:
                  type: string
                  maxLength: 200
                locale:
                  type: string
                  enum:
                    - en_US
                    - es_MX
                messageText:
                  type: string
                  maxLength: 1024
                  minLength: 1
                consentConfirmed:
                  type: boolean
                  enum:
                    - true
              required:
                - channel
                - targetChannelId
                - phoneNumber
                - locale
                - messageText
                - consentConfirmed
              additionalProperties: false
      responses:
        '202':
          description: Accepted and queued, not delivered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationStartResponse'
        default:
          $ref: '#/components/responses/Error'
components:
  schemas:
    ConversationStartResponse:
      type: object
      properties:
        replyId:
          type: string
        requestEventId:
          type: string
        conversationId:
          type: string
        status:
          type: string
          enum:
            - queued
      required:
        - conversationId
        - status
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: M2M_AUTH_INSUFFICIENT_SCOPE
            message:
              type: string
            details:
              type: object
              additionalProperties: true
      example:
        error:
          code: M2M_AUTH_INSUFFICIENT_SCOPE
          message: M2M credential does not have required scope.
          details:
            requiredScopes:
              - conversations:write
            missingScopes:
              - conversations:write
  responses:
    Error:
      description: Structured error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Visito M2M API key
      description: Server-side tenant-scoped credential created from Build > API Keys.

````