Chat Oratrix: Usando a API externa

Chatbot Flow da Oratrix
1

:receipt: VISÃO GERAL

A API do Chat Oratrix foi desenvolvida para permitir a integração segura e estruturada entre sistemas externos e o ecossistema de atendimento da Oratrix. Por meio dessa API, plataformas como CRMs, ERPs, sistemas proprietários e automações podem interagir diretamente com conversas, contatos, oportunidades e dados operacionais do Chat Oratrix.

Essa API segue o padrão OpenAPI 3 (OAS3) e está versionada, garantindo compatibilidade, previsibilidade e evolução controlada das integrações. Todas as requisições são realizadas através de endpoints REST, utilizando métodos HTTP padronizados e payloads no formato JSON.

A utilização da API do Chat Oratrix é indicada para cenários onde há necessidade de automação de processos, sincronização de dados, disparo de ações externas, registro de informações no atendimento e integração omnichannel, sempre mantendo o histórico centralizado no ambiente Oratrix.

Documentação para DEVs: https://chat.oratrix.com.br/#/docs

:globe_with_meridians: AMBIENTE E SERVIDOR DA API

A API é acessada por meio de um servidor dedicado, configurado conforme o ambiente do cliente (exemplo: Enterprise).

Exemplo de servidor exibido na documentação:

https://enterprise-60api.oratrix.com.br

:pushpin: Esse endpoint base deve ser utilizado como prefixo para todas as rotas da API.

:locked_with_key: AUTENTICAÇÃO E AUTORIZAÇÃO

A API do Chat Oratrix utiliza controle de autorização, exigindo credenciais válidas para execução das requisições.

Antes de consumir qualquer endpoint protegido, é necessário:

  • Autenticar-se na API
  • Informar corretamente os headers exigidos
  • Garantir que o token ou credencial tenha permissão para o recurso acessado

:warning: Requisições sem autorização válida serão automaticamente recusadas.

:puzzle_piece: ORGANIZAÇÃO DOS RECURSOS DA API

A documentação da API do Chat Oratrix está organizada em módulos funcionais, facilitando a compreensão e o uso conforme o objetivo da integração.

:open_file_folder: Módulos disponíveis na API

:small_blue_diamond: General

Conjunto de endpoints responsáveis por ações gerais da API, como envio de mensagens, interações básicas e operações centrais do Chat Oratrix.

:small_blue_diamond: Tags

Endpoints destinados ao gerenciamento de tags, permitindo classificar conversas, contatos ou atendimentos de forma estruturada e automatizada.

:small_blue_diamond: Oportunidades

Recursos voltados à integração com o funil comercial, possibilitando criação, atualização e acompanhamento de oportunidades de venda vinculadas aos atendimentos.

:small_blue_diamond: Produtos

Endpoints responsáveis pelo gerenciamento de produtos, permitindo associar itens, planos ou serviços às oportunidades ou registros do chat.

:small_blue_diamond: Pipeline Steps

Recursos que permitem interagir com as etapas do pipeline, automatizando movimentações, atualizações de status e controle do fluxo comercial.

:gear: PADRÕES TÉCNICOS DA API

A API do Chat Oratrix segue os seguintes padrões técnicos:

  • Comunicação via protocolo HTTP/HTTPS
  • Payloads no formato application/json
  • Versionamento explícito da API
  • Estrutura RESTful
  • Organização por recursos e contextos funcionais
  • Compatibilidade com ferramentas como Swagger / OpenAPI

Esses padrões garantem uma integração estável, escalável e compatível com boas práticas de mercado.

General

:outbox_tray: Envio de mensagem ou template

Endpoint

Método: POST

/v1/api/external/{id}

Descrição

Este endpoint permite o envio de mensagens simples ou mensagens baseadas em template para um contato, registrando automaticamente a interação dentro do Chat Oratrix.

É utilizado em cenários de:

  • automação de mensagens
  • disparos transacionais
  • integrações com sistemas externos
  • execuções vinculadas a webhooks

Parâmetro obrigatório (Path)

Nome Tipo Descrição
id string Identificador da integração, canal ou fila configurada no Chat Oratrix

Corpo da requisição

Formato: application/json

Exemplo

{
  "body": "Sua mensagem",
  "number": "556400000000",
  "externalKey": "ID_UNICA_DO_SISTEMA_CLIENTE_PARA_EXECUTAR_UMA_ACAO_COM_WEBHOOK",
  "note": {
    "body": "Sua nota interna",
    "mediaUrl": "Url com anexo a ser adicionado na nota interna"
  }
}

Campos do request

Campo Obrigatório Descrição
body Sim Texto da mensagem enviada ao contato
number Sim Número do contato no formato internacional
externalKey Não Identificador do sistema externo para rastreamento e ações via webhook
note.body Não Texto de nota interna associada à conversa
note.mediaUrl Não URL de anexo vinculado à nota interna

A nota interna não é exibida ao cliente, apenas para operadores e gestores.

Resposta

Código Descrição
200 Requisição executada com sucesso

Formato:

application/json

:page_facing_up: Listar templates (WABA)

Endpoint

Método: GET

/v1/api/external/template/{id}

Descrição

Retorna a lista de templates de mensagens aprovados (WABA) disponíveis para uso no envio de mensagens automáticas.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
id string Identificador da integração ou canal

Resposta

Código Descrição
200 Listagem retornada com sucesso

Formato:

application/json

:busts_in_silhouette: Listar usuários

Endpoint

Método: GET

/v1/api/external/users/{id}

Descrição

Permite listar os usuários vinculados ao ambiente do Chat Oratrix, possibilitando integrações com sistemas externos que precisam identificar operadores ou responsáveis pelos atendimentos.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
id string Identificador da integração

Resposta

Código Descrição
200 Listagem realizada com sucesso

Formato:

application/json

Tags

:page_facing_up: Listar tags

Endpoint

Método: GET

/v1/api/external/{apiId}/tags

Descrição

Retorna a lista de tags cadastradas no ambiente do Chat Oratrix.
As tags são utilizadas para classificação, organização e automação de conversas e atendimentos.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
apiId string ID da API / integração configurada

Resposta

Código Descrição
200 Lista de tags retornada com sucesso

Formato:

application/json

Exemplo de resposta

[
  {
    "tag": "string",
    "color": "string",
    "userId": 0
  }
]

:plus: Criar múltiplas tags

Endpoint

Método: POST

/v1/api/external/{apiId}/tags

Descrição

Permite criar múltiplas tags em um único request.
Todas as tags enviadas são validadas antes do cadastro.
Caso qualquer tag seja inválida, nenhuma será criada.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
apiId string ID da API / integração configurada

Corpo da requisição

Formato: application/json

Exemplo

[
  {
    "tag": "Tag 1",
    "color": "#FF0000",
    "userId": null
  },
  {
    "tag": "Tag 2",
    "color": "#00FF00",
    "userId": null
  },
  {
    "tag": "Tag 3",
    "color": "#0000FF",
    "userId": null
  }
]

Campos do request

Campo Obrigatório Descrição
tag Sim Nome da tag
color Sim Cor da tag em formato hexadecimal
userId Não ID do usuário associado à tag (ou null para uso geral)

Resposta – sucesso

Código Descrição
200 Tags criadas com sucesso

Formato:

application/json

Exemplo de resposta

[
  {
    "id": 1,
    "tag": "Tag 1",
    "color": "#FF0000",
    "userId": null,
    "tenantId": 1,
    "isActive": true,
    "createdAt": "2025-05-20T12:00:00.000Z",
    "updatedAt": "2025-05-20T12:00:00.000Z"
  }
]

Resposta – erro de validação

Código Descrição
400 Erro de validação

Formato:

{
  "error": "Erro na validação da tag \"Nome inválido\": tag is a required field"
}

:wastebasket: Remover tag

Endpoint

Método: DELETE

/v1/api/external/{apiId}/tags/{tagId}

Descrição

Remove uma tag específica do ambiente do Chat Oratrix.

Parâmetros obrigatórios (Path)

Nome Tipo Descrição
apiId string ID da API / integração
tagId string ID da tag a ser removida

Resposta

Código Descrição
200 Tag removida com sucesso

Formato:

{
  "message": "Tag removida com sucesso."
}

Oportunidades

:page_facing_up: Listar oportunidades

Endpoint

Método: GET

/v1/api/external/{apiId}/opportunities

Descrição

Lista as oportunidades cadastradas no Chat Oratrix, permitindo o uso de filtros opcionais para refinar os resultados.

Parâmetros

Path

Nome Tipo Descrição
apiId string ID da API / integração

Query (opcionais)

Nome Tipo Descrição
searchParam string Termo de busca
pageNumber string Número da página (padrão: 1)
status string Status da oportunidade (open, won, lost)
startDate string (date) Data inicial para filtro
endDate string (date) Data final para filtro
contactId number ID do contato
pipelineStepId number ID da etapa do pipeline
responsibleId string ID do responsável

Resposta

Código Descrição
200 Lista de oportunidades

Formato:

{
  "success": true,
  "data": [
    {}
  ],
  "count": 0,
  "hasMore": true,
  "message": "string"
}

:plus: Criar oportunidade

Endpoint

Método: POST

/v1/api/external/{apiId}/opportunities

Descrição

Cria uma nova oportunidade, podendo associar contato, responsável, etapa do pipeline e produtos.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
apiId string ID da API / integração

Corpo da requisição

Formato: application/json

Exemplo

{
  "name": "Venda de produto X",
  "description": "Oportunidade de venda para cliente importante",
  "value": 1500,
  "expectedCloseDate": "2025-12-31T23:59:59.000Z",
  "contactId": 123,
  "responsibleId": "456",
  "pipelineStepId": 1,
  "userId": "456",
  "productsOpportunity": [
    {
      "productId": 789,
      "amount": 2,
      "value": 750
    }
  ]
}

Resposta – sucesso

Código Descrição
201 Oportunidade criada com sucesso

Formato:

{
  "success": true,
  "data": {},
  "message": "string"
}

Resposta – erro

Código Descrição
400 Erro de validação

Formato:

{
  "error": "string"
}

:magnifying_glass_tilted_right: Buscar oportunidade por ID

Endpoint

Método: GET

/v1/api/external/{apiId}/opportunities/{opportunityId}

Descrição

Busca uma oportunidade específica utilizando seu ID.

Parâmetros (Path)

Nome Tipo Descrição
apiId string ID da API
opportunityId string ID da oportunidade

Respostas

Código Descrição
200 Oportunidade encontrada
404 Oportunidade não encontrada

Formato (200):

{
  "success": true,
  "data": {},
  "message": "string"
}

:pencil: Atualizar oportunidade

Endpoint

Método: PUT

/v1/api/external/{apiId}/opportunities/{opportunityId}

Descrição

Atualiza os dados de uma oportunidade existente, como valor, responsável ou etapa do pipeline.

Parâmetros (Path)

Nome Tipo Descrição
apiId string ID da API
opportunityId string ID da oportunidade

Corpo da requisição

Formato: application/json

Exemplo

{
  "name": "Venda de produto X - Atualizada",
  "description": "Descrição atualizada",
  "value": 2000,
  "expectedCloseDate": "2025-12-31T23:59:59.000Z",
  "responsibleId": "789",
  "pipelineStepId": 2,
  "userId": "456"
}

Respostas

Código Descrição
200 Oportunidade atualizada com sucesso
400 Erro de validação
404 Oportunidade não encontrada

Formato (200):

{
  "success": true,
  "data": {},
  "message": "string"
}

:counterclockwise_arrows_button: Atualizar status da oportunidade

Endpoint

Método: PUT

/v1/api/external/{apiId}/opportunities/{opportunityId}/status

Descrição

Atualiza o status da oportunidade, podendo ser:

  • open
  • won
  • lost

Parâmetros (Path)

Nome Tipo Descrição
apiId string ID da API
opportunityId string ID da oportunidade

Corpo da requisição

Formato: application/json

Exemplo – marcar como ganha

{
  "status": "won",
  "pipelineStepId": 5
}

Respostas

Código Descrição
200 Status atualizado com sucesso
400 Erro de validação (ex: motivo obrigatório para status lost)
404 Oportunidade não encontrada

Formato (200):

{
  "success": true,
  "data": {},
  "message": "string"
}

Produtos

:page_facing_up: Listar produtos ativos

Endpoint

Método: GET

/v1/api/external/{apiId}/products

Descrição

Lista todos os produtos ativos disponíveis para o tenant, permitindo que sistemas externos consultem os itens que podem ser associados a oportunidades no Chat Oratrix.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
apiId string ID da API / integração

Resposta – sucesso

Código Descrição
200 Lista de produtos ativos retornada com sucesso

Formato:

{
  "success": true,
  "data": [
    {
      "id": 0,
      "name": "string",
      "description": "string",
      "value": 0,
      "duration": 0,
      "isActive": true,
      "tenantId": 0,
      "userId": 0,
      "createdAt": "2026-01-31T20:01:16.936Z",
      "updatedAt": "2026-01-31T20:01:16.936Z"
    }
  ],
  "message": "Produtos ativos listados com sucesso"
}

Campos do retorno

Campo Descrição
id Identificador do produto
name Nome do produto
description Descrição do produto
value Valor do produto
duration Duração associada ao produto
isActive Indica se o produto está ativo
tenantId Identificador do tenant
userId Usuário responsável pelo cadastro
createdAt Data de criação
updatedAt Data da última atualização

Respostas – erro

Código Descrição
401 Token inválido
403 Sessão não autorizada

Pipeline Steps

:page_facing_up: Listar pipeline steps

Endpoint

Método: GET

/v1/api/external/{apiId}/pipeline-steps

Descrição

Lista todas as etapas do pipeline (pipeline steps) disponíveis para o tenant, permitindo que sistemas externos consultem as fases do funil comercial utilizadas nas oportunidades do Chat Oratrix.

Parâmetro obrigatório (Path)

Nome Tipo Descrição
apiId string ID da API / integração

Resposta – sucesso

Código Descrição
200 Lista de pipeline steps retornada com sucesso

Formato:

{
  "success": true,
  "data": [
    {
      "id": 0,
      "name": "string",
      "color": "string",
      "order": 0,
      "tenantId": 0,
      "createdAt": "2026-01-31T20:02:28.436Z",
      "updatedAt": "2026-01-31T20:02:28.436Z"
    }
  ],
  "message": "Pipeline steps listados com sucesso"
}

Campos do retorno

Campo Descrição
id Identificador da etapa do pipeline
name Nome da etapa
color Cor associada à etapa
order Ordem da etapa no pipeline
tenantId Identificador do tenant
createdAt Data de criação
updatedAt Data da última atualização

Respostas – erro

Código Descrição
401 Token inválido
403 Sessão não autorizada

Schemas

:incoming_envelope: Message

Schema utilizado para envio de mensagens simples via API externa.

{
  "body": "string",
  "number": "string",
  "mediaUrl": "string | null",
  "externalKey": "string",
  "onlyNote": true,
  "userId": 0,
  "forceTicketToUser": true,
  "note": {}
}

Campos

Campo Tipo Obrigatório Descrição
body string Sim Conteúdo da mensagem
number string Sim Número do contato (formato internacional)
mediaUrl string Não URL de mídia/anexo
externalKey string Sim Identificador externo para rastreio/webhook
onlyNote boolean Não Quando true, cria apenas uma nota sem enviar mensagem
userId number Não Usuário que receberá o ticket (exige forceTicketToUser=true)
forceTicketToUser boolean Não Redireciona o ticket para o usuário informado
note object Não Nota interna vinculada à conversa

:speech_balloon: WabaMessage

Schema utilizado para envio de mensagens via template (WABA).

{
  "number": "string",
  "templateId": "string",
  "params": [],
  "typeTemplate": "string | null",
  "templateMediaId": "string | null",
  "externalKey": "string",
  "onlyNote": true,
  "userId": 0,
  "forceTicketToUser": true,
  "note": {}
}

Campos

Campo Tipo Obrigatório Descrição
number string Sim Número do contato
templateId string Sim ID do template aprovado
params array Não Parâmetros do template
typeTemplate string Não Tipo do template
templateMediaId string Não ID de mídia associada ao template
externalKey string Sim Identificador externo
onlyNote boolean Não Cria apenas nota interna
userId number Não Usuário responsável pelo ticket
forceTicketToUser boolean Não Força atribuição do ticket
note object Não Nota interna

:label: Tag

Schema utilizado para criação de tags.

{
  "tag": "string",
  "color": "#000000",
  "userId": 0
}

Campos

Campo Tipo Obrigatório Descrição
tag string Sim Nome da tag
color string Sim Cor hexadecimal (#RRGGBB)
userId number Não Usuário associado à tag

:package: ProductOpportunity

Schema utilizado para associação de produtos a oportunidades.

{
  "productId": 0,
  "amount": 1,
  "value": 0
}

Campos

Campo Tipo Obrigatório Descrição
productId number Sim ID do produto
amount number Sim Quantidade (mínimo 1)
value number Sim Valor unitário

:plus: CreateOpportunity

Schema utilizado para criação de oportunidades.

{
  "name": "string",
  "description": "string",
  "value": 0,
  "expectedCloseDate": "date-time",
  "contactId": 0,
  "responsibleId": "string",
  "pipelineStepId": 0,
  "userId": "string",
  "productsOpportunity": []
}

Campos principais

  • name (obrigatório): nome da oportunidade
  • contactId (obrigatório): ID do contato
  • responsibleId (obrigatório): responsável
  • pipelineStepId (obrigatório): etapa do pipeline
  • userId (obrigatório): usuário da ação

:pencil: UpdateOpportunity

Schema utilizado para atualização de oportunidades.

{
  "name": "string",
  "description": "string",
  "value": 0,
  "expectedCloseDate": "date-time",
  "responsibleId": "string",
  "pipelineStepId": 0,
  "userId": "string",
  "productsOpportunity": []
}

Todos os campos são opcionais, exceto userId.

:counterclockwise_arrows_button: UpdateOpportunityStatus

Schema utilizado para alteração de status da oportunidade.

{
  "status": "open | won | lost",
  "pipelineStepId": 0,
  "gainOrLossReasonId": "string",
  "note": "string",
  "userId": "string"
}

Observações importantes

  • gainOrLossReasonId é obrigatório quando status = lost
  • userId é sempre obrigatório

:page_facing_up: ProductResponse

Schema de retorno de produtos.

Campos principais:

  • id, name, description
  • value, duration
  • isActive
  • tenantId, userId
  • createdAt, updatedAt

:repeat_button: PipelineStepResponse

Schema de retorno de pipeline steps.

Campos principais:

  • id, name, color, order
  • tenantId
  • createdAt, updatedAt

:bar_chart: OpportunityResponse

Schema padrão de retorno único.

{
  "success": true,
  "data": {},
  "message": "string"
}

:bookmark_tabs: OpportunityListResponse

Schema de listagem de oportunidades.

{
  "success": true,
  "data": [],
  "count": 0,
  "hasMore": true,
  "message": "string"
}

:bar_chart: RESULTADOS / BENEFÍCIOS

:check_mark: Integração direta entre sistemas externos e o Chat Oratrix
:check_mark: Automação de processos operacionais e comerciais
:check_mark: Centralização de dados e histórico de atendimento
:check_mark: Maior controle sobre funil de vendas e interações
:check_mark: Redução de tarefas manuais e retrabalho operacional

:receipt: RESUMO FINAL

A API do Chat Oratrix oferece uma base robusta e organizada para integrações avançadas, permitindo que sistemas externos interajam diretamente com atendimentos, dados comerciais e fluxos operacionais, mantendo tudo centralizado, seguro e rastreável dentro do ecossistema Oratrix.

:label: KEYWORDS

Chat Oratrix, API Chat, integração, automação, OpenAPI

:speech_balloon: VERSÃO CURTA – RESPOSTA PARA WHATSAPP

Pergunta: Para que serve a API do Chat Oratrix?

Resposta:

A API do Chat Oratrix permite integrar sistemas externos ao atendimento, possibilitando envio de mensagens, uso de tags, controle de oportunidades, produtos e etapas do pipeline.

Ela é ideal para automações, CRMs e sistemas que precisam interagir diretamente com o Chat Oratrix de forma segura e organizada.