URAs

CRUD completo para URAs (fluxos de atendimento automatizado) — vinculadas a uma conexão SIP ou WhatsApp, definem os passos que acontecem antes ou no lugar do agente de IA.

Endpoints

Método	Rota	Descrição
GET	`/api/v1/uras`	Lista URAs
POST	`/api/v1/uras`	Cria uma URA
GET	`/api/v1/uras/{ura}`	Exibe uma URA
PUT/PATCH	`/api/v1/uras/{ura}`	Atualiza uma URA
DELETE	`/api/v1/uras/{ura}`	Remove uma URA

Filtros de listagem

search, is_active, agent_id.

Campos base

Campo	Tipo	Obrigatório	Descrição
`name`	string, max 255	Sim	Nome da URA.
`description`	string	Não	Descrição livre.
`is_active`	boolean	Não	Padrão: conforme cadastro.
`agent_id`	integer	Sim	Agente vinculado à URA.
`whatsapp_connection_id`	integer	Condicional	ID de uma conexão WhatsApp da conta.
`sip_connection_id`	integer	Condicional	ID de uma conexão SIP da conta.
`automation_id`	string, max 255	Não	Identificador de automação externa associada.
`actions`	array	Não	Passos do fluxo da URA, executados em ordem.

:::info Regra de exclusividade Uma URA pertence a exatamente um canal: informe whatsapp_connection_id ou sip_connection_id, nunca os dois. Na criação, um dos dois é obrigatório. Na atualização, enviar apenas um dos dois substitui o canal atual (o outro é automaticamente zerado); enviar ambos ao mesmo tempo retorna erro de validação. :::

Cada item de `actions`

Campo	Tipo	Obrigatório	Descrição
`name`	string, max 255	Sim	Nome do passo.
`type`	string	Sim	`transfer`, `search_info` ou `question_form`.
`config`	array	Depende do tipo	Configuração específica do passo (veja abaixo).

`type: transfer`

config.transfer_to é obrigatório e define o destino: agent, agent_context, human ou webhook.

`transfer_to`	Campos adicionais em `config`
`agent`	`agent_id` (obrigatório) — agente que assume a chamada.
`agent_context`	`context_agent_ids` (obrigatório, array de IDs de agentes) e `context_instructions` (opcional).
`webhook`	`webhook_url` (obrigatório, URL válida).
`human`	`human_target` (obrigatório: `contact` ou `team`); se `contact`, `contact_id` obrigatório; se `team`, `team_id` obrigatório.

`type: search_info`

Campo em `config`	Descrição
`tool_ids`	Array de IDs de ferramentas de agente usadas para buscar a informação.

`type: question_form`

Campo em `config`	Descrição
`formulario_id`	Obrigatório — ID de um formulário da conta a ser aplicado.

Exemplos de curl por tipo de action

Os exemplos abaixo atualizam a URA 9, substituindo sua lista de actions por um único passo — troque pelo id real da sua URA. Para adicionar mais de um passo na mesma requisição, inclua vários objetos no array actions, como no exemplo de criação de URA mais abaixo.

`transfer` → `agent`

Transfere a chamada para outro agente de IA.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Transferir para agente especialista",
            "type": "transfer",
            "config": { "transfer_to": "agent", "agent_id": 15 }
          }
        ]
      }'

`transfer` → `agent_context`

Transfere a chamada para outro agente, repassando contexto adicional sobre a conversa.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Transferir com contexto para agentes de suporte",
            "type": "transfer",
            "config": {
              "transfer_to": "agent_context",
              "context_agent_ids": [15, 18],
              "context_instructions": "Cliente já informou que é sobre uma cobrança indevida."
            }
          }
        ]
      }'

`transfer` → `webhook`

Dispara um webhook externo em vez de transferir para um agente ou humano.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Notificar sistema externo",
            "type": "transfer",
            "config": { "transfer_to": "webhook", "webhook_url": "https://meusistema.com/webhooks/ura" }
          }
        ]
      }'

`transfer` → `human` (`contact`)

Transfere a chamada para um contato humano específico.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Transferir para o gerente",
            "type": "transfer",
            "config": { "transfer_to": "human", "human_target": "contact", "contact_id": 21 }
          }
        ]
      }'

`transfer` → `human` (`team`)

Transfere a chamada para uma equipe/fila.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Transferir para o suporte N2",
            "type": "transfer",
            "config": { "transfer_to": "human", "human_target": "team", "team_id": 4 }
          }
        ]
      }'

`search_info`

Consulta ferramentas do agente para responder a uma pergunta antes de seguir o fluxo.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Consultar status do pedido",
            "type": "search_info",
            "config": { "tool_ids": [3, 5] }
          }
        ]
      }'

`question_form`

Aplica um formulário de perguntas ao cliente durante o fluxo.

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "actions": [
          {
            "name": "Coletar dados do lead",
            "type": "question_form",
            "config": { "formulario_id": 7 }
          }
        ]
      }'

Exemplos com curl

Listar URAs

curl "$ROUXINOL_URL/api/v1/uras?is_active=true" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Criar uma URA

curl -X POST "$ROUXINOL_URL/api/v1/uras" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "URA Comercial",
        "agent_id": 12,
        "sip_connection_id": 5,
        "actions": [
          {
            "name": "Coletar dados do lead",
            "type": "question_form",
            "config": { "formulario_id": 7 }
          },
          {
            "name": "Transferir para humano",
            "type": "transfer",
            "config": { "transfer_to": "human", "human_target": "team", "team_id": 4 }
          }
        ]
      }'

Exibir uma URA

curl "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Atualizar uma URA

curl -X PATCH "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Remover uma URA

curl -X DELETE "$ROUXINOL_URL/api/v1/uras/9" \
  -H "Authorization: Bearer $ROUXINOL_TOKEN"

Endpoints​

Filtros de listagem​

Campos base​

Cada item de actions​

type: transfer​

type: search_info​

type: question_form​

Exemplos de curl por tipo de action​

transfer → agent​

transfer → agent_context​

transfer → webhook​

transfer → human (contact)​

transfer → human (team)​

search_info​

question_form​

Exemplos com curl​