Guia de Integração

Guia de Integração para aplicações terceiras que consomem o provider `webhook` do Otima Agente.

Público-alvo	Integradores responsáveis por conectar aplicações terceiras ao fluxo do Otima Agente.
Endpoint de integração	POST https://syncwebhook.otima.digital/v5/runner/tokens/{token}/webhook/session
Objetivo	Receber mensagens da aplicação integradora e devolver ações padronizadas para execução local.
Identificadores de sessão	external_id = id externo da sessão no integrador; session_id = id interno da sessão no Otima Agente.

Escopo deste guia

Este material descreve o contrato de entrada e saída, o comportamento da sessão, o significado das ações retornadas e dois fluxos completos de referência para integração.

1. Visão Geral

• Endpoint de integração: POST https://syncwebhook.otima.digital/v5/runner/tokens/{token}/webhook/session

• Objetivo: receber mensagens da aplicação terceira e devolver ações padronizadas (actions) para execução.

• Chaves da sessão: external_id é o id único da sessão no sistema integrador; session_id é o id interno da sessão no Otima Agente.

2. Onde pegar o token no Agente (Canvas)

Use o card Início > Canais > Webhook para copiar a URL da API e identificar o token do fluxo.

Figura 1 — Local no Canvas onde a URL do webhook e o token do fluxo podem ser copiados.

Importante

A URL do webhook/token é configurada por fluxo. Cada fluxo possui o seu próprio token.

3. Fluxo de exemplo no Canvas

A imagem abaixo representa um fluxo real contendo mensagens, validação, transferência, desligamento e finalização.

Figura 2 — Exemplo de fluxo completo no Canvas com caminhos de sucesso, exceção e transferência.

4. Contrato de Entrada (request)

Endpoint

POST /v5/runner/tokens/{token}/webhook/session
Content-Type: application/json
Accept: application/json

Payload mínimo

{
  "external_id": "0000000000001247806",
  "text": "Ola"
}

Importante

O external_id pode ser acessado em qualquer ponto do Canvas e é interpretado em runtime pelo Otima Agente estando disponível por toda a sessão.

Payload com `contact` (opcional no primeiro evento)

{
  "external_id": "0000000000001247806",
  "text": "Ola",
  "contact": {
    "id": 12345678900,
    "identifier": "30392286789",
    "name": "Joao",
    "full_name": "Joao da Silva",
    "gender": "M",
    "country": "Brasil",
    "province": "SP",
    "city": "Campinas",
    "birth_date": "1990/01/05",
    "age": 36,
    "channel": {
      "type": "phone",
      "label": "tel1",
      "address": "5511999999900"
    },
    "extra": {
      "risco": 10,
      "carteira": "itau"
    }
  }
}

Regra importante de `contact`

• Se enviado no primeiro evento da sessão, o contact é injetado em runtime e fica disponível durante toda a sessão.

• Eventos seguintes da mesma sessão devem manter o mesmo external_id.

• O reenvio de contact em eventos posteriores não deve ser usado como mecanismo de atualização de contexto da mesma sessão.

5. Contrato de Saída (response)

O provider `webhook` responde com um envelope padronizado:

{
  "actions": [
    {
      "type": "message",
      "name": "text",
      "payload": {
        "text": "..."
      }
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Semântica de `actions[]`

Campo	Descrição	Exemplos
type	Categoria da ação.	message / command
name	Nome da ação devolvida pelo fluxo.	text / hangup / transfer / finish_flow
payload	Parâmetros associados à ação.	{"text":"..."} / {"reason":"flow_finished"} / {...}
actions[]	Lista ordenada de instruções a serem consumidas pelo integrador.	Processar sempre na ordem recebida.

Ações mais comuns

1. Mensagem de texto

{
  "type": "message",
  "name": "text",
  "payload": {
    "text": "Agora voce pode por favor confirmar os 4 ultimos digitos do seu celular?"
  }
}

2. Comando de desligar

{
  "type": "command",
  "name": "hangup",
  "payload": {
    "reason": "flow_finished"
  }
}

3. Comando de transferência (voz)

{
  "type": "command",
  "name": "transfer",
  "payload": {
    "did": "1000",
    "lcr": "lCaiotrk"
  }
}

4. Comando de transferência (message)

{
  "type": "command",
  "name": "transfer",
  "payload": {
    "phone": "551140047755"
  }
}

5. Comando de desfecho

{
  "type": "command",
  "name": "finish_flow",
  "payload": {
    "result": "success"
  }
}

6. Exemplo completo 1 (desfecho de sucesso)

Início da sessão (aplicação terceira)

curl --location 'https://syncwebhook.otima.digital/v5/runner/tokens/10189b11c2b3455fb2c09825821191d92b49254d5da0423582aafff8543c81a8/webhook/session' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "0000000000001247806",
    "text": "Ola",
    "contact": {
        "id": 12345678900,
        "identifier": "30392286789",
        "name": "Joao",
        "full_name": "Joao da Silva",
        "gender": "M",
        "country": "Brasil",
        "province": "SP",
        "city": "Campinas",
        "birth_date": "1990/01/05",
        "age": 36,
        "channel": {
            "type": "phone",
            "label": "tel1",
            "address": "5511999999900"
        },
        "extra": {
            "risco": 10,
            "carteira": "itau"
        }
    }
}'

Action 1 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "5511999999900 e o seu numero! que legal!"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 2 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "Agora voce pode por favor confirmar os 4 ultimos digitos do seu celular?"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Resposta 1 (aplicação terceira)

curl --location 'https://syncwebhook.otima.digital/v5/runner/tokens/10189b11c2b3455fb2c09825821191d92b49254d5da0423582aafff8543c81a8/webhook/session' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "0000000000001247806",
    "text": "9900"
}'

Action 3 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "Perfeito! O numero informado 5511999999900 esta correto! Obrigado, tchau!"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 4 (Otima Agente)

{
  "actions": [
    {
      "name": "hangup",
      "payload": {
        "reason": "flow_finished"
      },
      "type": "command"
    }
  ],
  "component_id": "hangup",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 5 (Otima Agente)

{
  "actions": [
    {
      "name": "finish_flow",
      "payload": {
        "result": "success"
      },
      "type": "command"
    }
  ],
  "component_id": "finish_flow",
  "external_session_id": "0000000000001247806",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "29036c1a-6e58-49fb-afee-b762cde1fb91",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

7. Exemplo completo 2 (desfecho com transferência)

Início da sessão (aplicação terceira)

curl --location 'https://syncwebhook.otima.digital/v5/runner/tokens/10189b11c2b3455fb2c09825821191d92b49254d5da0423582aafff8543c81a8/webhook/session' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "0000000000001247807",
    "text": "Ola",
    "contact": {
        "id": 12345678900,
        "identifier": "30392286789",
        "name": "Joao",
        "full_name": "Joao da Silva",
        "gender": "M",
        "country": "Brasil",
        "province": "SP",
        "city": "Campinas",
        "birth_date": "1990/01/05",
        "age": 36,
        "channel": {
            "type": "phone",
            "label": "tel1",
            "address": "5511999999900"
        },
        "extra": {
            "risco": 10,
            "carteira": "itau"
        }
    }
}'

Action 1 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "Que bom que voce ligou! Identifiquei o seu numero de origem como 5511999999900"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247807",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "3659abf2-3bf2-40bb-9351-1bcd2140e972",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 2 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "Agora voce pode por favor confirmar os 4 ultimos digitos do seu celular?"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247807",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "3659abf2-3bf2-40bb-9351-1bcd2140e972",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Resposta 1 (aplicação terceira)

curl --location 'https://syncwebhook.otima.digital/v5/runner/tokens/10189b11c2b3455fb2c09825821191d92b49254d5da0423582aafff8543c81a8/webhook/session' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "external_id": "0000000000001247807",
    "text": "1122"
}'

Action 3 (Otima Agente)

{
  "actions": [
    {
      "name": "text",
      "payload": {
        "text": "O codigo informado nao bateu! Vou te transferir para a equipe de seguranca digital. Aguarde por favor!"
      },
      "type": "message"
    }
  ],
  "component_id": "send_message",
  "external_session_id": "0000000000001247807",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "3659abf2-3bf2-40bb-9351-1bcd2140e972",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 4 (Otima Agente)

{
  "actions": [
    {
      "name": "transfer",
      "payload": {
        "did": "1000",
        "lcr": "8"
      },
      "type": "command"
    }
  ],
  "component_id": "transfer",
  "external_session_id": "0000000000001247807",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "3659abf2-3bf2-40bb-9351-1bcd2140e972",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

Action 5 (Otima Agente)

{
  "actions": [
    {
      "name": "finish_flow",
      "payload": {
        "result": "transfer"
      },
      "type": "command"
    }
  ],
  "component_id": "finish_flow",
  "external_session_id": "0000000000001247807",
  "flow_id": "7bf1c8ff-8492-4f4c-95f6-59311aa7b386",
  "flow_slug": "testeinbound001",
  "session_id": "3659abf2-3bf2-40bb-9351-1bcd2140e972",
  "workspace_uuid": "bdbf27ec-0dd4-483a-aee5-78c9172e6cf4"
}

8. Regras de consumo para integradores

Processamento recomendado por resposta:

1. Ler actions[] na ordem.

2. Para cada item:

• type=message e name=text -> enviar ou exibir o texto ao usuário final.

• type=command e name=hangup -> encerrar o canal ou a chamada.

• type=command e name=transfer -> executar a transferência conforme o payload.

• type=command e name=finish_flow -> registrar o desfecho final e encerrar o workflow local.

1. Quando houver nova entrada do usuário, reenviar para o mesmo endpoint com o mesmo external_id.

9. `finish_flow`: desfecho oficial da jornada

O comando `finish_flow` é o marcador final do resultado de negócio do fluxo.

{
  "type": "command",
  "name": "finish_flow",
  "payload": {
    "result": "success"
  }
}

Resultados esperados em payload.result:

Valor	Significado
success	Concluído com sucesso.
unsuccess	Concluído sem sucesso.
neutral	Finalização neutra.
transfer	Finalização por transferência.

Recomendação importante de integração

• Persista payload.result no sistema integrador como o desfecho oficial da conversa.

• Antes de publicar a integração em produção, valide: persistência do external_id, tratamento ordenado de actions[], suporte a comandos e registro do resultado final retornado por finish_flow.

Boas práticas

• Use external_id único e estável por sessão.

• Envie contact somente no primeiro evento, quando quiser semear contexto.

• Trate actions como uma lista ordenada de instruções.

• Não assuma que sempre virá apenas text; comandos como hangup, transfer e finish_flow fazem parte do contrato.