EvoAI Platform

https://docs.evolutionfoundation.com.br/
Admin
EvoAI Platform is a comprehensive REST API infrastructure providing AI agent management, CRM...
Tokens:398,251
Snippets:2,142
Trust Score:2.1
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install, Start, and Enable Nginx

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nginx

Installs Nginx, starts the service, and ensures it runs on system boot. Verifies the status to confirm it's operational.

```bash
apt-get install -y nginx
systemctl start nginx
systemctl enable nginx
systemctl status nginx
```

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

### Execute SetupOrion for Automated Installation

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/setup-orion

Run this command on a clean VPS to initiate the automated installation of Evolution API infrastructure, including Docker, Traefik, and Portainer. The script will guide you through the setup process.

```bash
bash <(curl -sSL setup.oriondesign.art.br)
```

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

### Install and Manage API with PM2

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm

Install PM2 globally, start the API process, set up PM2 to start on system boot, and save the current process list.

```bash
npm install pm2 -g
pm2 start 'npm run start:prod' --name ApiEvolution
pm2 startup
pm2 save --force
```

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

### Run Setup Command

Source: https://docs.evolutionfoundation.com.br/self-hosted

Execute this command to build Docker images, set up the database, populate initial data, and start all services. The first run may take 15-20 minutes.

```bash
make setup
```

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

### Install MySQL Server on Ubuntu

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/database

Install the MySQL server package on Ubuntu systems using apt-get. This is a prerequisite for local MySQL setup.

```bash
sudo apt-get update
sudo apt-get install mysql-server
```

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

### Install Docker

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/docker

Download and execute the official Docker installation script.

```bash
curl -fsSL https://get.docker.com | bash
```

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

### Start Redis Server Service

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/redis

Start the Redis server service on Ubuntu after installation. This command ensures the Redis daemon is running.

```bash
sudo service redis-server start
```

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

### CLI Activation URL Output Example

Source: https://docs.evolutionfoundation.com.br/licensing/activation

Example of how the registration URL can be presented to an operator in a command-line interface.

```text
─────────────────────────────────────────────────────────────────
  Ativação de licença Evolution API
─────────────────────────────────────────────────────────────────

  Para ativar, abra no navegador:

  https://license.evolutionfoundation.com.br/register?token=abc123def...

  Aguardando confirmação... (expira em 30 minutos)
─────────────────────────────────────────────────────────────────
```

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

### Install Redis Server on Ubuntu

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/redis

Install the Redis server package on Ubuntu systems. This is the first step for a local Redis installation.

```bash
sudo apt-get update
sudo apt-get install redis-server
```

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

### Install Evo-Nexus Service Manually

Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started.md

Command to manually install the evo-nexus systemd service using a provided script.

```bash
sudo bash install-service.sh

```

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

### Install NVM

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm

Download and install the Node Version Manager (NVM) script. This is the first step to managing Node.js versions.

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
```

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

### Example API Request

Source: https://docs.evolutionfoundation.com.br/api-reference/authentication

Example of how to make a GET request to the /api/v1/agents endpoint using the API Access Token.

```APIDOC
## Example API Request

### Description
Example of how to make a GET request to the /api/v1/agents endpoint using the API Access Token.

### Method
GET

### Endpoint
https://api.evoai.app/api/v1/agents

### Headers
- `api_access_token`: <SEU_TOKEN_UUID>
- `Content-Type`: application/json
```

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

### Start All Services

Source: https://docs.evolutionfoundation.com.br/self-hosted

Use this command to bring all platform services online.

```bash
make start
```

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

### Install PostgreSQL on Ubuntu

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/database

Install PostgreSQL and its contrib package on Ubuntu systems using apt-get. This is a prerequisite for local PostgreSQL setup.

```bash
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib
```

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

### Build and Start Evolution API

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm

Build the production-ready application and start the Evolution API. These commands prepare the application for deployment and run it.

```bash
npm run build
npm run start:prod
```

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

### Step 1: Initiate Registration

Source: https://docs.evolutionfoundation.com.br/licensing/activation

Initiates the license registration process by sending product details to the registration server. This is the first step when an instance detects no local API key.

```APIDOC
## POST /v1/register/init

### Description
Initiates the license registration process. This endpoint should be called when an instance detects that it does not have a locally saved `api_key`.

### Method
POST

### Endpoint
/v1/register/init

### Parameters
#### Request Body
- **tier** (string) - Required - `community` or `beta`
- **version** (string) - Required - Version of the Evolution product (e.g., `2.4.0`)
- **instance_id** (UUID v4) - Required - Local identifier for the instance, generated once and persisted.

### Request Example
```json
{
  "tier": "community",
  "version": "2.4.0",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### Response
#### Success Response (200)
- **register_url** (string) - The URL the operator needs to visit to complete the activation.
- **token** (string) - A token associated with the registration request, used for subsequent polling.

#### Response Example
```json
{
  "register_url": "https://license.evolutionfoundation.com.br/register?token=abc123def456...",
  "token": "abc123def456..."
}
```

### Errors
- **400** `INVALID_TIER`: The provided tier is not `community` or `beta`.
- **400** `INVALID_BODY`: The request body is malformed JSON.
- **429** `RATE_LIMIT`: Exceeded the rate limit of 10 inits per hour per IP.
```

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

### OpenAPI Specification for List Pipelines

Source: https://docs.evolutionfoundation.com.br/evo-ai-crm/list-all-pipelines

Defines the GET /api/v1/pipelines endpoint, including request parameters, response schemas, and example payloads.

```yaml
openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Pipelines
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3000
    description: Development server
    variables:
      port:
        default: '3000'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/pipelines:
    get:
      summary: List all pipelines
      description: Get all active pipelines with stages, items, tasks info and services
      operationId: list-pipelines
      responses:
        '200':
          description: Pipelines retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                  - meta
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/pipeline'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Pipelines retrieved successfully
              example:
                success: true
                data:
                  - id: 550e8400-e29b-41d4-a716-446655440000
                    name: Sales Pipeline Q1
                    account_id: 123e4567-e89b-12d3-a456-426614174000
                    created_by_id: 660e8400-e29b-41d4-a716-446655440001
                    description: Lead management and sales opportunity management.
                    pipeline_type: sales
                    visibility: private
                    is_active: true
                    custom_fields:
                      attributes: []
                    item_count: 0
                    conversations_count: 0
                    created_at: '2024-01-15T10:30:00Z'
                    updated_at: '2024-01-15T10:30:00Z'
                    stages:
                      - id: 770e8400-e29b-41d4-a716-446655440002
                        name: New Lead
                        pipeline_id: 550e8400-e29b-41d4-a716-446655440000
                        position: 1
                        color: '#3B82F6'
                        stage_type: 0
                        automation_rules:
                          description: New interested contacts
                        custom_fields:
                          attributes: []
                        created_at: '2024-01-15T10:30:00Z'
                        updated_at: '2024-01-15T10:30:00Z'
                        item_count: 0
                        items: []
                      - id: 880e8400-e29b-41d4-a716-446655440003
                        name: Qualification
                        pipeline_id: 550e8400-e29b-41d4-a716-446655440000
                        position: 2
                        color: '#F59E0B'
                        stage_type: 0
                        automation_rules:
                          description: Interest and fit verification
                        custom_fields:
                          attributes: []
                        created_at: '2024-01-15T10:30:00Z'
                        updated_at: '2024-01-15T10:30:00Z'
                        item_count: 0
                        items: []
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Pipelines retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
```

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

### Example SKILL.md for New Skill Creation

Source: https://docs.evolutionfoundation.com.br/evo-nexus/skills/overview

This markdown example demonstrates the `SKILL.md` file for a new skill, `my-new-skill`. It includes a detailed description for triggering the skill and outlines the steps for collecting data from Linear and GitHub, generating a summary, and saving the output.

```markdown
---
name: my-new-skill
description: "Gerar um resumo semanal de standup do time a partir de issues do Linear e PRs do GitHub. Acione quando o usuário disser 'resumo de standup', 'update do time' ou 'o que o time fez'."
---

# Resumo de Standup do Time

Gera um resumo semanal da atividade do time.

## Passo 1 — Coletar Dados do Linear

Use a skill `/int-linear-review` para buscar:
- Issues concluídas esta semana
- Issues em progresso
- Bloqueios

## Passo 2 — Coletar Dados do GitHub

Use a skill `/int-github-review` para buscar:
- PRs mergeados esta semana
- PRs em review

## Passo 3 — Gerar Resumo

Formate como relatório markdown com seções:
- Concluído
- Em Progresso
- Bloqueado
- Destaques

## Passo 4 — Salvar

Salve em `workspace/projects/reports/[C] YYYY-MM-DD-standup.md`
```

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

### OpenAPI Specification for Conversation Details

Source: https://docs.evolutionfoundation.com.br/evo-ai-crm/conversation-details

Defines the GET endpoint for fetching conversation details, including success and error response examples.

```yaml
openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Conversations
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3000
    description: Development server
    variables:
      port:
        default: '3000'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/conversations/{conversation_id}:
    parameters:
      - $ref: '#/components/parameters/conversation_id'
    get:
      summary: Conversation Details
      description: >-
        Get all details regarding a conversation with all messages in the
        conversation
      operationId: get-details-of-a-conversation
      responses:
        '200':
          description: Conversation details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                  - meta
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data: ef100033-a566-4635-a714-3e7c8222a2e6
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Conversation details retrieved successfully
              example:
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  account_id: 123e4567-e89b-12d3-a456-426614174000
                  inbox_id: 660e8400-e29b-41d4-a716-446655440001
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Conversation details retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid request parameters
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request parameters
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/conversations/{conversation_id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid or missing authentication token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/conversations/{conversation_id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Access denied
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: Access denied
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/conversations/{conversation_id}
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
```

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

### Practical Example 1: Basic Request with API Access Token

Source: https://docs.evolutionfoundation.com.br/api-reference/authentication

A practical example demonstrating how to make a basic authenticated request using an API Access Token in Bash.

```APIDOC
## Practical Examples

### Example 1: Basic Request with API Access Token

```bash
#!/bin/bash

# Configuration
# The Base URL varies by environment
API_URL="https://api.evoai.app/api/v1/agents"
API_TOKEN="<YOUR_TOKEN_UUID>"

# Make request
curl -X GET "$API_URL" \
  -H "api_access_token: $API_TOKEN" \
  -H "Content-Type: application/json" | jq .
```
```

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

### OpenAPI Specification for TOTP Setup

Source: https://docs.evolutionfoundation.com.br/evo-auth-service/setup-totp-authentication

Defines the POST endpoint for initializing TOTP authentication, including request body requirements and error handling examples.

```yaml
openapi: 3.0.1
info:
  title: Evolution Foundation - Auth Service - Multi Factor Authentication
  description: Authentication and user and account management
  version: v1.0.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3001
    description: Development server
    variables:
      port:
        default: '3001'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/mfa/setup_totp:
    post:
      summary: Setup TOTP authentication
      description: Setup Time-based One-Time Password (TOTP) authentication
      operationId: setupTOTP
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  description: Current user password for verification
              required:
                - password
      responses:
        '200':
          description: TOTP setup successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MFASetupResponse'
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_password:
                  summary: Invalid password
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid password or TOTP already enabled
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/mfa/setup_totp
                      method: POST
                totp_already_enabled:
                  summary: TOTP already enabled
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: TOTP is already enabled for this user
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/mfa/setup_totp
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized access
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/mfa/setup_totp
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Access forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You do not have permission to access this resource
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/mfa/setup_totp
                      method: POST
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                not_found:
                  summary: User not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: User not found
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/mfa/setup_totp
                      method: POST
        '500':
          description: Internal Server Error (server error)
          content:
            application/json:
              schema:
```

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

### Instalação com Docker

Source: https://docs.evolutionfoundation.com.br/evolution-go/installation

Instale e execute o Evolution Go rapidamente usando Docker. Siga os passos para clonar o repositório, configurar as variáveis de ambiente e construir/executar a imagem Docker.

```APIDOC
## Instalação com Docker

### Passo 1: Clone o repositório

```bash
git clone https://git.evoai.app/Evolution/evolution-go.git
cd evolution-go
```

### Passo 2: Configure as variáveis de ambiente

```bash
cp .env.example .env
```

Edite o arquivo `.env` com suas configurações:

```env
# Porta do servidor
SERVER_PORT=8080

# Nome do cliente
CLIENT_NAME=evolution

# Chave de API global (altere para uma chave segura!)
GLOBAL_API_KEY=sua-chave-secura-aqui

# Banco de dados (PostgreSQL)
POSTGRES_AUTH_DB=postgresql://postgres:password@postgres:5432/evogo_auth?sslmode=disable
POSTGRES_USERS_DB=postgresql://postgres:password@postgres:5432/evogo_users?sslmode=disable
DATABASE_SAVE_MESSAGES=false

# Logs
WADEBUG=INFO
LOGTYPE=console
```

### Passo 3: Build e execução

```bash
# Build da imagem Docker
make docker-build

# Executar o container
make docker-run
```

O serviço estará disponível em `http://localhost:8080`.
```

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

### OpenAPI Specification for Setup Channel Provider

Source: https://docs.evolutionfoundation.com.br/evo-ai-crm/setup-channel-provider

Defines the POST endpoint for configuring channel providers, including request body schema and error response examples.

```yaml
openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Inboxes
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3000
    description: Development server
    variables:
      port:
        default: '3000'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/inboxes/{id}/setup_channel_provider:
    post:
      summary: Setup Channel Provider
      description: Configures the channel provider integration for the inbox
      operationId: setupChannelProvider
      parameters:
        - name: id
          in: path
          schema:
            type: string
            format: uuid
          description: ID of the inbox
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - provider
              properties:
                provider:
                  type: string
                  description: Provider name (twilio, whatsapp, evolution, etc.)
                  example: whatsapp
                provider_config:
                  type: object
                  description: Provider-specific configuration
                  additionalProperties: true
      responses:
        '200':
          description: Channel provider configured successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                  - meta
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    nullable: true
                    description: Channel provider configuration data
                    properties:
                      provider:
                        type: string
                        example: whatsapp
                      status:
                        type: string
                        example: configured
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Channel provider configured successfully
              example:
                success: true
                data:
                  provider: whatsapp
                  status: configured
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Channel provider configured successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/inboxes/{id}/setup_channel_provider
                      method: POST
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/inboxes/{id}/setup_channel_provider
                      method: POST
        '403':
          description: Forbidden (insufficient permissions)
          content:
```

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

### Instalar EvoNexus via Clone Manual

Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started.md

Clona o repositório do EvoNexus e executa o script de setup interativo para configurar o ambiente.

```bash
git clone --depth 1 https://github.com/evolution-foundation/evo-nexus.git
cd evo-nexus

# Wizard de setup interativo
make setup
# Ou: python setup.py
```

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

### OpenAPI Specification for Show Inbox Agent Bot

Source: https://docs.evolutionfoundation.com.br/evo-ai-crm/show-inbox-agent-bot

Defines the GET endpoint for retrieving agent bot details, including path parameters, response schemas, and error handling examples.

```yaml
openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Inboxes
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3000
    description: Development server
    variables:
      port:
        default: '3000'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/inboxes/{id}/agent_bot:
    get:
      summary: Show Inbox Agent Bot
      description: See if an agent bot is associated to the Inbox
      operationId: getInboxAgentBot
      parameters:
        - name: id
          in: path
          schema:
            type: string
            format: uuid
          description: ID of the inbox
          required: true
      responses:
        '200':
          description: Agent bot retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - data
                  - meta
                  - message
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    nullable: true
                    description: Agent bot data or null if not associated
                    properties:
                      id:
                        type: integer
                        description: Agent bot ID
                        example: 1
                      name:
                        type: string
                        description: Agent bot name
                        example: Support Bot
                      description:
                        type: string
                        nullable: true
                        description: Agent bot description
                        example: Automated support assistant
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Agent bot retrieved successfully
              example:
                success: true
                data:
                  id: 1
                  name: Support Bot
                  description: Automated support assistant
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Agent bot retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                bad_request:
                  summary: Invalid request data
                  value:
                    success: false
                    error:
                      code: BAD_REQUEST
                      message: Invalid request data
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/inboxes/{id}/agent_bot
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    success: false
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/inboxes/{id}/agent_bot
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Forbidden
                  value:
                    success: false
                    error:
```

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

### Request Example with Tenant

Source: https://docs.evolutionfoundation.com.br/api-reference/authentication

Examples of making requests, showing how the tenant can be identified automatically via token or explicitly via a header.

```APIDOC
### Example of Request with Tenant

```bash
# The tenant can be identified automatically via token
# The Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>" \
  -H "Content-Type: application/json"

# Or explicitly via header (if supported by the service)
# Note: The header name varies by service - consult specific documentation
# The Base URL varies by environment
curl -X GET https://api.evoai.app/api/v1/agents \
  -H "api_access_token: <YOUR_TOKEN_UUID>" \
  -H "X-Account-ID: <tenant-id>" \
  -H "Content-Type: application/json"
```

> **Note**: Consult the specific documentation for each service to confirm the tenant identification method used. The header name may vary between services.
```

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

### Show Contact API Endpoint Definition

Source: https://docs.evolutionfoundation.com.br/evo-ai-crm/show-contact

Defines the GET /api/v1/contacts/{id} endpoint for retrieving a contact by ID. Includes parameters, success response with data example, and error responses.

```yaml
openapi: 3.0.4
info:
  title: Evolution Foundation - CRM Service - Contacts
  description: Management of contacts, conversations, inboxes, labels and macros
  version: 1.1.0
servers:
  - url: https://api.evoai.app
    description: Production server
  - url: http://localhost:3000
    description: Development server
    variables:
      port:
        default: '3000'
  - url: '{customUrl}'
    description: Custom server
    variables:
      customUrl:
        default: https://your-instance.com
        description: Enter your server URL
security: []
paths:
  /api/v1/contacts/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the contact
    get:
      summary: Show Contact
      description: Get a contact belonging to the account using ID
      operationId: contactDetails
      responses:
        '200':
          description: Contact retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    $ref: '#/components/schemas/extended_contact'
                  meta:
                    type: object
                    properties:
                      timestamp:
                        type: string
                        format: date-time
                        description: Response timestamp
                        example: '2024-01-15T10:30:00Z'
                  message:
                    type: string
                    description: Success message
                    example: Contact retrieved successfully
              example:
                success: true
                data:
                  id: 550e8400-e29b-41d4-a716-446655440000
                  name: John Doe
                  email: john@example.com
                  phone_number: '+5574999999999'
                  identifier: john-doe-123
                  account_id: 123e4567-e89b-12d3-a456-426614174000
                  custom_attributes: {}
                  created_at: '2024-01-15T10:30:00Z'
                  updated_at: '2024-01-15T10:30:00Z'
                meta:
                  timestamp: '2024-01-15T10:30:00Z'
                message: Contact retrieved successfully
        '400':
          description: Bad Request (invalid data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                validation_error:
                  summary: Invalid request parameters
                  value:
                    success: false
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request parameters
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/contacts/{id}
                      method: GET
        '401':
          description: Unauthorized (invalid or missing token)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_token:
                  summary: Invalid or missing token
                  value:
                    success: false
                    error:
                      code: INVALID_TOKEN
                      message: Invalid token
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/contacts/{id}
                      method: GET
        '403':
          description: Forbidden (insufficient permissions)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  summary: Access forbidden
                  value:
                    success: false
                    error:
                      code: FORBIDDEN
                      message: You do not have permission to access this resource
                    meta:
                      timestamp: '2024-01-15T10:30:00Z'
                      path: /api/v1/contacts/{id}
                      method: GET
        '404':
          description: Not Found (resource not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                contact_not_found:
                  summary: Contact not found
                  value:
                    success: false
                    error:
                      code: NOT_FOUND
                      message: Contact not found

```

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

### Instalar EvoNexus com npx

Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started.md

Executa o EvoNexus diretamente via npx, que baixa e inicia o wizard de setup interativo automaticamente.

```bash
npx @evoapi/evo-nexus
```

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

### Start Scheduler Locally

Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started.md

Command to start the scheduler for running automated routines locally.

```bash
make scheduler

```

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

### Copy Environment File

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm

Copy the example environment file to create your own configuration file. This file will store sensitive information and API settings.

```bash
cp ./.env.example ./.env
```

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

### Instalar e rodar EvoNexus com Docker

Source: https://docs.evolutionfoundation.com.br/evo-nexus/getting-started.md

Baixa as imagens oficiais e inicia o EvoNexus usando Docker Compose. Acesse o wizard de configuração em http://localhost:8080.

```bash
curl -O https://raw.githubusercontent.com/evolution-foundation/evo-nexus/main/docker-compose.hub.yml
docker compose -f docker-compose.hub.yml up -d
open http://localhost:8080
```

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

### Install uv package manager

Source: https://docs.evolutionfoundation.com.br/evo-nexus/skills/ai-image-creator.md

Command to install the uv package manager if it is missing from the environment.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
brew install uv
```

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

### Start MySQL Service

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/database

Start the MySQL service on your system. This command is typically used on Linux systems.

```bash
sudo service mysql start
```

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

### Practical Example 3: Python with API Access Token

Source: https://docs.evolutionfoundation.com.br/api-reference/authentication

A practical example in Python demonstrating how to create a client to make authenticated requests using an API Access Token.

```APIDOC
### Example 3: Python with API Access Token

```python
import os
import requests

class EvoAIClient:
    def __init__(self, api_token, api_url):
        self.api_token = api_token
        self.api_url = api_url
    
    def request(self, method, endpoint, **kwargs):
        """Makes an authenticated request with API Access Token"""
        url = f"{self.api_url}{endpoint}"
        
        headers = kwargs.get('headers', {})
        headers['api_access_token'] = self.api_token
        headers['Content-Type'] = 'application/json'
        kwargs['headers'] = headers
        
        response = requests.request(method, url, **kwargs)
        
        if response.status_code == 401:
            raise Exception('Invalid or missing token. Please check your API Access Token.')
        
        if response.status_code == 403:
            raise Exception('Permission denied to access this resource')
        
        response.raise_for_status()
        return response

```

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

### Start PostgreSQL Service

Source: https://docs.evolutionfoundation.com.br/evolution-api/requirements/database

Start the PostgreSQL service on your system. This command is typically used on Linux systems.

```bash
sudo service postgresql start
```

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

### GET /instance/connect/{instanceName}

Source: https://docs.evolutionfoundation.com.br/evolution-api/connect-instance

Initiates the connection process for a specific WhatsApp instance.

```APIDOC
## GET /instance/connect/{instanceName}

### Description
Connects a specified instance to WhatsApp.

### Method
GET

### Endpoint
/instance/connect/{instanceName}

### Parameters
#### Path Parameters
- **instanceName** (string) - Required - WhatsApp instance name

### Response
#### Success Response (200)
- **pairingCode** (string) - Pairing code if available
- **code** (string) - Connection code
- **base64** (string) - Base64 representation of the connection QR code
- **count** (integer) - Connection count

#### Error Response (400, 401, 403, 404, 500)
- **success** (boolean) - Indicates failure
- **error** (object) - Contains error code and message
- **meta** (object) - Metadata regarding the request
```

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

### Install Project Dependencies

Source: https://docs.evolutionfoundation.com.br/evolution-api/install/nvm

Navigate into the project directory and install all necessary Node.js dependencies using npm. This step is crucial before configuring and running the API.

```bash
cd evolution-api
npm install
```
Tokens:
Raw