### Install Dimedove Messenger Widget

Source: https://docs.dimedove.com/developer/messenger/installation

Integrates the Dimedove Messenger into a website by adding a custom HTML element and loading the required JavaScript library. Users must replace the placeholder attributes with their specific agent ID and publishable key.

```html
<dimedove-messenger agent-id="YOUR_AGENT_ID" publishable-key="YOUR_PUBLISHABLE_KEY" />
<script
  src="https://unpkg.com/@dimedove/messenger@latest/dist/messenger.js"
  crossorigin="anonymous"
  async
></script>
```

--------------------------------

### GET /apps/{app_id}/config

Source: https://docs.dimedove.com/api-reference/applications/get-app-config

Retrieves the active configuration and agent settings for a specified application.

```APIDOC
## GET /apps/{app_id}/config

### Description
Returns the app's active configuration and agent settings.

### Method
GET

### Endpoint
/apps/{app_id}/config

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the app.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **app_id** (string) - Unique identifier for the app.
- **stream** (boolean) - Whether streaming (Server-Sent Events) is enabled by default for this app's responses.
- **generative_ui** (boolean) - Whether generative UI is enabled. When true, responses may include 'data-spec' parts for dynamic UI rendering.
- **agent** (object) - The AI agent configuration for this app.
  - **name** (string | null) - The display name of the AI agent associated with this app.
  - **config** (object) - The agent's UI configuration settings.
    - **primary_color** (string | null) - The primary brand color for the agent's UI, as a hex code (e.g. '#0f0e0d').
    - **secondary_color** (string | null) - The secondary brand color for the agent's UI, as a hex code.

#### Response Example
```json
{
  "app_id": "cln0j1x7h000008l57g74a1b7",
  "stream": true,
  "generative_ui": true,
  "agent": {
    "name": "My AI Agent",
    "config": {
      "primary_color": "#0f0e0d",
      "secondary_color": "#ffffff"
    }
  }
}
```

#### Error Response (401, 403, 404)
- **error** (object) - The error detail object.
  - **message** (string) - A human-readable description of the error.
  - **type** (string) - The error type identifier (e.g. 'invalid_api_key', 'not_found', 'rate_limit_exceeded').
  - **param** (string | null) - The parameter that caused the error, if applicable.
  - **code** (string | null) - An error code providing additional detail, if applicable.

#### Error Response Example
```json
{
  "error": {
    "message": "Invalid API key provided.",
    "type": "invalid_api_key",
    "param": null,
    "code": null
  }
}
```
```

--------------------------------

### API Configuration Guide

Source: https://docs.dimedove.com/platform/agents/tasks/api

This section outlines the core components for configuring API tasks, allowing your agent to make HTTP requests to external services.

```APIDOC
## API Configuration

API tasks enable your agent to perform HTTP requests to external services, providing full control over request construction for actions like data retrieval, form submission, or workflow triggering.

### Configuration Components

#### HTTP Method

Defines the type of HTTP request:
*   **GET**: Retrieve data.
*   **POST**: Submit data to create a new resource.
*   **PUT**: Replace an existing resource entirely.
*   **PATCH**: Partially update an existing resource.
*   **DELETE**: Remove a resource.

#### URL

The HTTPS endpoint for the agent to call. Can include path parameters using curly braces (e.g., `https://api.example.com/users/{userId}`).

#### Path Parameters

Dynamic segments within the URL that are replaced at runtime. Each parameter requires:
*   **Key**: Matches the placeholder in the URL (e.g., `userId`).
*   **Value type**: A static value or a reference to a task input.

#### Query Parameters

Parameters appended to the URL's query string. Can be static or sourced from task inputs.

#### Headers

HTTP headers sent with the request. Common headers include:
*   `Authorization`: For API keys or bearer tokens.
*   `Content-Type`: Typically `application/json`.
*   Custom headers required by the specific API.

#### Request Body

For POST, PUT, and PATCH requests, this defines the JSON structure of the request body. Supports:
*   **Static values**: Fixed values with type conversion (text, number, decimal, boolean).
*   **Input references**: Values collected from the visitor.
*   **Arrays**: Lists of items, static or from inputs.
*   **Nested objects**: Complex structures up to three levels deep.

### Task Inputs

Information collected from visitors during a conversation, used as dynamic values in API requests. Each input has:
*   **Name**: Display name shown in configuration.
*   **Key**: Reference key used in the request (auto-generated from name).
*   **Type**: Data type (text, number, decimal, boolean).
*   **Required**: Whether the agent must collect this input.
*   **AI Inferred**: Whether the agent can extract this from conversation context.

Common input templates (first name, last name, email, phone) are available for quick setup.

### Testing

Test your API configuration before deployment:
1.  **URL Preview**: View the constructed URL.
2.  **JSON Preview**: Inspect the request body structure.
3.  **Test Values**: Provide sample input values.
4.  **Execute Test**: Send a request and review the response (status, headers, body).
```

--------------------------------

### API Authentication Example (Bash)

Source: https://docs.dimedove.com/api-reference/overview

Demonstrates how to authenticate API requests using a Bearer token with your secret API key. Ensure your API key is kept secure and not exposed in client-side code.

```bash
Authorization: Bearer sk_live_your_api_key
```

--------------------------------

### GET /v1/apps/{app_id}/config

Source: https://docs.dimedove.com/developer/apps/api-keys

Retrieves the configuration for a specific application using Bearer token authentication.

```APIDOC
## GET /v1/apps/{app_id}/config

### Description
Retrieves the configuration settings for a specified application. This endpoint requires a valid secret API key.

### Method
GET

### Endpoint
https://api.dimedove.com/v1/apps/{app_id}/config

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the application.

### Request Example
```bash
curl -X GET https://api.dimedove.com/v1/apps/{app_id}/config \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Response
#### Success Response (200)
- **config** (object) - The configuration object for the requested application.

#### Response Example
{
  "app_id": "app_123",
  "status": "active",
  "settings": {}
}
```

--------------------------------

### Sample Request Body for chat.started Event

Source: https://docs.dimedove.com/developer/webhooks/event-types

This JSON object represents the sample request body for the `chat.started` event. It is triggered when a new conversation begins, typically initiated by a user's message. The payload includes a unique webhook ID, the event type, a timestamp, and data specific to the chat, such as the chat ID and creation time.

```json
{
  "id": "webhook_123456789",
  "type": "chat.started",
  "created": 1708646472,
  "data": {
    "chat_id": "8b146471-e88e-4322-86af-016cd36fd216",
    "created": 1708646471
  }
}
```

--------------------------------

### GET /conversations/{id}

Source: https://docs.dimedove.com/api-reference/conversations/get-conversation

Retrieves a single conversation including the full history of messages and function calls.

```APIDOC
## GET /conversations/{id}

### Description
Retrieves a single conversation with its complete history of messages and function calls, sorted chronologically.

### Method
GET

### Endpoint
/conversations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the conversation.

### Request Example
GET /conversations/conv_12345

### Response
#### Success Response (200)
- **id** (string) - The conversation ID
- **messages** (array) - List of message objects
- **function_calls** (array) - List of function call history

#### Response Example
{
  "id": "conv_12345",
  "messages": [],
  "function_calls": []
}
```

--------------------------------

### Documentation Index API

Source: https://docs.dimedove.com/api-reference/conversations/send-message

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

```APIDOC
## GET /llms.txt

### Description
Fetches the complete documentation index for the LLMs API. This index can be used to discover all available API endpoints and resources.

### Method
GET

### Endpoint
/llms.txt

### Parameters
None

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **documentation_index** (string) - A string containing the documentation index, typically in markdown format, listing available API pages.

#### Response Example
```
# Documentation Index

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

# Send message

> Sends a user message to the conversation and returns the AI agent's response. Supports both streaming (Server-Sent Events) and non-streaming (JSON) response modes. This endpoint is rate-limited.
```
```

--------------------------------

### GET /apps/{app_id}/conversations

Source: https://docs.dimedove.com/api-reference/conversations/list-conversations

Retrieves a paginated list of conversations associated with a specific application ID.

```APIDOC
## GET /apps/{app_id}/conversations

### Description
Returns a paginated list of all conversations for the specified app. Supports cursor-based pagination with configurable sort order.

### Method
GET

### Endpoint
https://api.dimedove.com/v1/apps/{app_id}/conversations

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the app.

#### Query Parameters
- **limit** (integer) - Optional - Maximum number of conversations to return. Range: 1-100. Default: 20.
- **after** (string) - Optional - A cursor for forward pagination. Returns conversations created after the conversation with this ID.
- **before** (string) - Optional - A cursor for backward pagination. Returns conversations created before the conversation with this ID.
- **order** (string) - Optional - Sort order by creation time. Either 'asc' or 'desc'. Default: desc.

### Request Example
GET /apps/my-app-id/conversations?limit=10&order=desc

### Response
#### Success Response (200)
- **object** (string) - The object type. Always 'list'.
- **data** (array) - The array of conversation objects for the current page.
- **first_id** (string|null) - The ID of the first conversation in the returned page.
- **last_id** (string|null) - The ID of the last conversation in the returned page.
- **has_more** (boolean) - Whether there are additional conversations beyond this page.

#### Response Example
{
  "object": "list",
  "data": [],
  "first_id": "conv_123",
  "last_id": "conv_456",
  "has_more": false
}
```

--------------------------------

### GET /v1/apps/{app_id}/conversations

Source: https://docs.dimedove.com/api-reference/overview

Retrieve a paginated list of conversations associated with a specific application.

```APIDOC
## GET /v1/apps/{app_id}/conversations

### Description
Fetches a list of conversations for the given application ID using cursor-based pagination.

### Method
GET

### Endpoint
https://api.dimedove.com/v1/apps/{app_id}/conversations

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the application.

#### Query Parameters
- **limit** (integer) - Optional - Number of results to return (1-100). Default: 20.
- **after** (string) - Optional - Cursor for forward pagination (conversation ID).
- **before** (string) - Optional - Cursor for backward pagination (conversation ID).
- **order** (string) - Optional - Sort order: 'asc' or 'desc'. Default: 'desc'.

### Response
#### Success Response (200)
- **object** (string) - Type of object (list).
- **data** (array) - List of conversation objects.
- **has_more** (boolean) - Indicates if more pages are available.

#### Response Example
{
  "object": "list",
  "data": [],
  "first_id": "conv_001",
  "last_id": "conv_020",
  "has_more": true
}
```

--------------------------------

### GET /apps/{app_id}/conversations/{conversation_id}

Source: https://docs.dimedove.com/api-reference/conversations/get-conversation

Retrieves a single conversation with its complete history of messages and function calls, sorted chronologically.

```APIDOC
## GET /apps/{app_id}/conversations/{conversation_id}

### Description
Retrieves a single conversation with its complete history of messages and function calls, sorted chronologically.

### Method
GET

### Endpoint
/apps/{app_id}/conversations/{conversation_id}

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the app.
- **conversation_id** (string) - Required - The unique identifier of the conversation.

### Request Example
```json
{
  "example": "No request body for GET request"
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the conversation.
- **object** (string) - The object type. Always 'conversation'.
- **created_at** (integer) - Unix timestamp (in seconds) of when the conversation was created.
- **external_user_id** (string | null) - The external user identifier associated with this conversation, if one was provided at creation.
- **title** (string | null) - The custom title set for this conversation, if any.
- **generated_title** (object | null) - AI-generated conversation title in supported locales. Keys are locale codes (e.g. 'en-ca', 'fr-ca').
- **items** (array) - The list of messages in the conversation.

#### Response Example
```json
{
  "id": "conv_abc123",
  "object": "conversation",
  "created_at": 1678886400,
  "external_user_id": "user_xyz789",
  "title": "My Awesome Conversation",
  "generated_title": {
    "en-ca": "My Awesome Conversation",
    "fr-ca": "Ma Super Conversation"
  },
  "items": [
    {
      "id": "msg_def456",
      "type": "message",
      "role": "user",
      "parts": [
        {
          "text": "Hello, AI!"
        }
      ],
      "created_at": 1678886401
    },
    {
      "id": "msg_ghi789",
      "type": "message",
      "role": "assistant",
      "parts": [
        {
          "text": "Hi there! How can I help you today?"
        }
      ],
      "created_at": 1678886402
    }
  ]
}
```

#### Error Response (401, 403, 404)
- **error** (object) - The error detail object.

#### Error Response Example
```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "The API key is invalid or expired."
  }
}
```
```

--------------------------------

### Sample Request Body for performance.recorded Event

Source: https://docs.dimedove.com/developer/webhooks/event-types

This JSON object illustrates the sample request body for the `performance.recorded` event, which occurs when an agent logs a successful Qualified Opportunity. The payload contains a webhook ID, event type, timestamp, and performance-related data, including the performance record ID, metric, details, and creation time.

```json
{
  "id": "webhook_123456789",
  "type": "performance.recorded",
  "created": 1708646472,
  "data": {
    "performance_record_id": "8b146471-e88e-4322-86af-016cd36fd216",
    "metric": "instructions",
    "details": "Instructions-Aligned Outcome: Successfully guided prospect through qualification process and captured key business requirements",
    "created": 1708646471
  }
}
```

--------------------------------

### POST /platform/agents/tasks/api

Source: https://docs.dimedove.com/llms.txt

Configures external API integrations for an AI agent, allowing it to perform specific actions or fetch data from third-party services.

```APIDOC
## POST /platform/agents/tasks/api

### Description
Configures an API integration for the agent to perform external actions or retrieve data during conversations.

### Method
POST

### Endpoint
/platform/agents/tasks/api

### Parameters
#### Request Body
- **agent_id** (string) - Required - The unique identifier of the agent.
- **api_endpoint** (string) - Required - The URL of the external service.
- **auth_token** (string) - Required - Authentication credentials for the external API.
- **method** (string) - Required - The HTTP method to use (GET, POST, etc.).

### Request Example
{
  "agent_id": "agt_12345",
  "api_endpoint": "https://api.example.com/v1/data",
  "method": "GET"
}

### Response
#### Success Response (200)
- **status** (string) - Confirmation of configuration update.
- **integration_id** (string) - Unique ID for the created integration.

#### Response Example
{
  "status": "success",
  "integration_id": "int_98765"
}
```

--------------------------------

### Sample Request Body for task.completed Event

Source: https://docs.dimedove.com/developer/webhooks/event-types

This JSON payload represents the sample request body for the `task.completed` event, indicating that an agent task has been finished. The structure includes a webhook ID, event type, timestamp, and task-specific data, such as task ID, task name, chat ID, and creation time.

```json
{
  "id": "webhook_123456789",
  "type": "task.completed",
  "created": 1708646472,
  "data": {
    "task_id": "8b146471-e88e-4322-86af-016cd36fd216",
    "task_name": "Send welcome email",
    "chat_id": "8b146471-e88e-4322-86af-016cd36fd216",
    "created": 1708646471
  }
}
```

--------------------------------

### GET /apps/{app_id}/metrics

Source: https://docs.dimedove.com/api-reference/applications/get-app-metrics

Returns aggregated usage metrics for a specific application, including total conversations, messages, and users.

```APIDOC
## GET /apps/{app_id}/metrics

### Description
Returns aggregated usage metrics for the app.

### Method
GET

### Endpoint
/apps/{app_id}/metrics

#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the app.

### Request Example
```json
{
  "example": "No request body needed for GET request."
}
```

### Response
#### Success Response (200)
- **total_conversations** (integer) - The total number of conversations created through this app.
- **total_messages** (integer) - The total number of messages exchanged across all conversations.
- **total_users** (integer) - The total number of unique users who have interacted with this app.

#### Response Example
```json
{
  "total_conversations": 1500,
  "total_messages": 75000,
  "total_users": 500
}
```

#### Error Responses
- **401** - Unauthorized
- **403** - Forbidden
- **404** - Not Found
```