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

# AI Processing

> How to send messages for intelligent processing

## Overview

The AI processing endpoint allows you to send text messages, images, audio, and PDFs for intelligent analysis. The system can respond synchronously or asynchronously (via postback).

## Main Endpoint

<Card>
  <strong>POST</strong> `/ai/process`
</Card>

## Payload Parameters

<ParamField body="tenant_id" type="string" required>
  Tenant ID (obtained from dashboard)
</ParamField>

<ParamField body="lead_id" type="string" required>
  ID of the lead sending the message
</ParamField>

<ParamField body="role" type="string" required>
  Sender role: `user`, `assistant`, `human`, `system`
</ParamField>

<ParamField body="content" type="string" required>
  Message content
</ParamField>

<ParamField body="message_type" type="string" required>
  Message type: `text`, `image`, `audio`, `pdf`
</ParamField>

<ParamField body="url" type="string">
  Media URL (required for types other than `text`)
</ParamField>

<ParamField body="debounce" type="boolean" default="false">
  When `true`, accumulates messages and sends response via postback
</ParamField>

<ParamField body="postback_url" type="string">
  URL to receive the response (required when `debounce: true`)
</ParamField>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.leavo.ai/ai/process" \
    -H "Authorization: Bearer your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "tenant_id": "tenant-uuid",
      "lead_id": "lead-uuid",
      "role": "user",
      "content": "Hello, I would like to know more about the product",
      "message_type": "text",
      "debounce": true,
      "postback_url": "https://your-webhook.com/callback"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.leavo.ai/ai/process', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      tenant_id: 'tenant-uuid',
      lead_id: 'lead-uuid',
      role: 'user',
      content: 'Hello, I would like to know more about the product',
      message_type: 'text',
      debounce: true,
      postback_url: 'https://your-webhook.com/callback'
    })
  });
  ```
</CodeGroup>

## Message Types

<AccordionGroup>
  <Accordion title="Text" icon="font">
    Simple text message.

    ```json theme={null}
    {
      "message_type": "text",
      "content": "Your message here"
    }
    ```
  </Accordion>

  <Accordion title="Image" icon="image">
    Send an image for visual analysis.

    ```json theme={null}
    {
      "message_type": "image",
      "content": "Optional description",
      "url": "https://example.com/image.jpg"
    }
    ```
  </Accordion>

  <Accordion title="Audio" icon="microphone">
    Send audio for transcription and analysis.

    ```json theme={null}
    {
      "message_type": "audio",
      "url": "https://example.com/audio.mp3"
    }
    ```
  </Accordion>

  <Accordion title="PDF" icon="file-pdf">
    Send a PDF for content extraction.

    ```json theme={null}
    {
      "message_type": "pdf",
      "url": "https://example.com/document.pdf"
    }
    ```
  </Accordion>
</AccordionGroup>

## Debounce Mode

<Info>
  Debounce mode is useful when you want to accumulate multiple messages before processing.
</Info>

### How It Works

1. When `debounce: true`, the system accumulates messages for a configured time
2. After the debounce time, all messages are processed together
3. The response is sent to the `postback_url`

### Request Flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant API
    participant AI
    participant Webhook

    Client->>API: POST /ai/process (debounce: true)
    API->>Client: 202 Accepted
    Note over API: Accumulates messages
    API->>AI: Process messages
    AI->>API: AI Response
    API->>Webhook: POST to postback_url
```

### Synchronous Response (without debounce)

When `debounce: false`, the response is returned immediately:

```json theme={null}
{
  "success": true,
  "response": "Hello! Sure, I can help with information about our product..."
}
```

### Postback Response

When `debounce: true`, the postback receives:

```json theme={null}
{
  "lead_id": "lead-uuid",
  "response": "Hello! Sure, I can help with information about our product...",
  "timestamp": "2024-01-15T10:30:00Z"
}
```