Referência NCCO

Um Objeto de Controle de Chamada (NCCO) é representado por um array JSON. Você pode usá-lo para controlar o fluxo de uma chamada da Voice API. Para que seu NCCO seja executado corretamente, os objetos JSON devem ser válidos.

Durante o desenvolvimento e o teste dos NCCOs, você pode usar o Voice Playground para experimentá-los de forma interativa. Você pode Leia mais sobre isso na Visão geral da Voice API ou vá diretamente para o Voice Playground no Painel de Controle.

Ações da NCCO

A ordem das ações no NCCO controla o fluxo da chamada. As ações que precisam ser concluídas antes que a próxima ação possa ser executada são síncrono. Outras ações são assíncrono. Ou seja, elas devem continuar passando pelas ações seguintes até que uma condição seja satisfeita. Por exemplo, um record a ação é encerrada quando o endOnSilence essa opção for atendida. Quando todas as ações no NCCO estiverem concluídas, a Chamada será encerrada.

As ações do NCCO e as opções e tipos para cada ação são:

Observe que, em todas as ações, o eventUrl O parâmetro DEVE ser um array, mesmo que contenha apenas um único valor.

Registro

Use o record procedimento para gravar uma chamada ou parte de uma chamada:

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from":"447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

A ação de registro é assíncrona. É possível definir uma condição síncrona — endOnSilence, timeOut ou endOnKey - para encerrar a gravação quando essa condição for atendida. Se nenhuma condição for definida, a gravação funcionará de maneira assíncrona e passará imediatamente para a próxima ação, sem interromper a gravação da chamada. A gravação só será encerrada e o evento relevante será enviado quando a chamada for encerrada. Isso é utilizado em cenários semelhantes ao monitoramento de chamadas.

Você pode transcrever uma gravação usando o transcription opção. Assim que a transcrição da gravação estiver concluída, será enviada uma notificação para um eventUrl. Usando as configurações de transcrição, você pode definir uma eventUrl e language para suas transcrições. Observe que esse é um recurso pago; as tarifas exatas podem ser consultadas no Preços da Voice API página na seção “Recursos programáveis”.

Para obter informações sobre o fluxo de trabalho a ser seguido, consulte Gravação.

Você pode usar as seguintes opções para controlar um record ação:

Configurações de transcrição

Registrar parâmetros de retorno

Veja o Referência sobre Webhooks para parâmetros de gravação ou transcrição que são retornados ao eventUrl.

Conversa

Você pode usar o conversation ação para criar conferências padrão ou moderadas, preservando o contexto da comunicação. Usando conversation com o mesmo name reutiliza o mesmo dado armazenado Conversa. A primeira pessoa a ligar para o número virtual atribuído à conversa é quem a cria. Essa ação é síncrona.

Os exemplos a seguir do NCCO mostram como configurar diferentes tipos de conversação. Você pode usar o answer_url Parâmetros da solicitação GET do webhook para garantir que um NCCO seja enviado aos participantes e outro ao moderador.

[
  {
    "action": "conversation",
    "name": "nexmo-conference-standard",
    "record": true,
    "transcription": {
      "eventUrl": [ "https://example.com/transcription" ],
      "eventMethod": "POST",
      "language": "he-IL"
    }
  }
]

// As the customer is the first person to join, there is no canHear/canSpeak entry
// The customer's leg ID is 6a4d6af0-55a6-4667-be90-8614e4c8e83c
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"],
  }
]

// The agent joins and can both hear, and speak to the customer
// The agent's leg ID is 533c0874-f43d-446c-a153-f35bf30783fa
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"], // Customer leg ID
    "canSpeak": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"] // Customer leg ID
  }
]

// Finally, the supervisor joins the conversation. They can hear both the customer
// and the agent, but only speak to the agent
// The supervisor's leg ID is e2833e43-db39-4c1a-b689-d17ad2cf3529
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c", "533c0874-f43d-446c-a153-f35bf30783fa"] // Customer leg ID, Agent leg ID
    "canSpeak": ["533c0874-f43d-446c-a153-f35bf30783fa"] // Agent leg ID
  }
]

[
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "record": true,
    "startOnEnter": true
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference. We will connect you when an agent is available"
  },
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"]
  }
]

Você pode usar as seguintes opções para controlar um conversa ação:

Conectar-se

Você pode usar o connect ação para conectar uma chamada a pontos de extremidade, como números de telefone ou uma extensão do VBC.

Essa ação é síncrona, após um conectar a próxima ação na pilha do NCCO é processada. Uma ação de conexão é encerrada quando o terminal que você está chamando está ocupado ou indisponível. Você liga para os terminais sequencialmente, aninhando ações de conexão.

Os exemplos a seguir do NCCO mostram como configurar diferentes tipos de conexões.

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001",
        "dtmfAnswer": "2p02p"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "ws://example.com/socket",
        "content-type": "audio/l16;rate=16000",
        "headers": {
            "name": "J Doe",
            "age": 40,
            "address": {
                "line_1": "Apartment 14",
                "line_2": "123 Example Street",
                "city": "New York City"
            },
            "system_roles": [183493, 1038492, 22],
            "enable_auditing": false
        },
        "authorization": {
            "type": "custom",
            "value": "Bearer eyJhbGciOi..."
        }
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "app",
        "user": "jamie"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "sip",
        "uri": "sip:rebekka@sip.mcrussell.com",
        "headers": { "location": "New York City", "occupation": "developer" }
      }
    ]
  }
]

[
  {
    "action": "connect",
    "from": "447700900000",
    "timeout": 5,
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/event-fallback"
    ],
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "voiceName": "Russell",
    "text": "Thank you for calling. Connecting you to extension."
  },
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "vbc",
        "extension": "111"
      }
    ]
  }
]

[
    {  
      "action": "talk",  
      "text": "Please wait while we connect you"
    },
    {
        "action": "connect",
        "eventUrl": [
          "https://example.com/events"
        ],
        "from": "447700900000",
        "endpoint": [
            {  
              "type": "sip",  
              "user": "john",
              "domain": "vonage-developer", 
              "headers":
                { 
                  "location": "New York City", 
                  "occupation": "developer"
                }
            }
        ]
    }
]

Você pode usar as seguintes opções para controlar um connect ação:

Tipos e valores de pontos finais

Telefone (PSTN) — números de telefone no formato E.164

Exemplo do shaken opção:

eyJhbGciOiJFUzI1NiIsInBwdCI6InNoYWtlbiIsInR5cCI6InBhc3Nwb3J0IiwieDV1IjoiaHR0cHM6Ly9jZXJ0LmV4YW1wbGUuY29tL3Bhc3Nwb3J0LnBlbSJ9.eyJhdHRlc3QiOiJBIiwiZGVzdCI6eyJ0biI6WyIxMjEyNTU1MTIxMiJdfSwiaWF0IjoxNjk0ODcwNDAwLCJvcmlnIjp7InRuIjoiMTQxNTU1NTEyMzQifSwib3JpZ2lkIjoiMTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDAwIn0.MEUCIQCrfKeMtvn9I6zXjE2VfGEcdjC2sm5M6cPqBvFyV9XkpQIgLxlvLNmC8DJEKexXZqTZ;info=<https://stir-provider.example.net/cert.cer>;alg=ES256;ppt="shaken"

Aplicativo - Conecte a chamada a um aplicativo compatível com RTC

WebSocket — o WebSocket ao qual se conectar

SIP — o terminal SIP ao qual se conectar

VBC — a extensão Vonage Business Cloud (VBC) para se conectar a

Conversa

O talk Essa ação envia uma mensagem de voz sintetizada para uma conversa.

O texto fornecido na ação de fala pode ser simples ou formatado usando SSML. As tags SSML fornecem instruções adicionais ao sintetizador de texto para fala, permitindo definir o tom, a pronúncia e combinar textos em vários idiomas. As tags SSML são baseadas em XML e enviadas diretamente na string JSON.

Por padrão, a ação “talk” é síncrona. No entanto, se você definir bargeIn para verdadeiro você deve definir um entrada ação posterior na pilha do NCCO. Os exemplos a seguir do NCCO mostram como enviar uma mensagem de fala sintetizada para uma conversa ou chamada:

[
  {
    "action": "talk",
    "text": "You are listening to a Call made with Voice API"
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Voice API I V R. ",
    "language": "en-GB",
    "bargeIn": false
  },
  {
    "action": "talk",
    "text": "Press 1 for maybe and 2 for not sure followed by the hash key",
    "language": "en-GB",
    "bargeIn": true
  },
  {
    "action": "input",
    "submitOnHash": true,
    "eventUrl": ["https://example.com/ivr"]
  }
]

[
  {
    "action": "talk",
    "text": "<speak><prosody rate='fast'>I can speak fast.</prosody></speak>"
  }
]

Você pode usar as seguintes opções para controlar um conversa ação:

Parâmetros de retorno da função Talk

Veja Referência sobre Webhooks para os parâmetros que são retornados à eventUrl.

Transmissão

O stream Essa ação permite enviar um fluxo de áudio para uma conversa

Por padrão, a ação do fluxo é síncrona. No entanto, se você definir bargeIn para verdadeiro você deve definir um entrada ação posterior na pilha do NCCO.

O exemplo a seguir do NCCO mostra como enviar um fluxo de áudio para uma conversa ou chamada:

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/music.mp3"]
  }
]

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/announcement.mp3"],
    "bargeIn": "true"
  },
  {
    "action": "input",
    "submitOnHash": "true",
    "eventUrl": ["https://example.com/ivr"]
  }
]

Você pode usar as seguintes opções para controlar um fluxo ação:

O fluxo de áudio mencionado deve ser um arquivo no formato MP3 ou WAV. Caso haja problemas com a reprodução do arquivo, codifique-o de acordo com as seguintes especificações técnicas: Que tipo de arquivos de áudio pré-gravados posso usar?

Cache-Control: public, max-age=360000

Parâmetros de retorno do fluxo

Veja Referência sobre Webhooks para os parâmetros que são retornados à eventUrl.

Entrada

Você pode usar o input ação para coletar os dígitos ou a entrada de voz da pessoa para quem você está ligando. Essa ação é síncrona: a Vonage processa a entrada e a encaminha no parâmetros enviado para o eventUrl ponto de extremidade do webhook que você configura em sua solicitação. Seu ponto de extremidade do webhook deve retornar outro NCCO que substitua o NCCO existente e controle a chamada com base na entrada do usuário. Você pode usar essa funcionalidade para criar uma Resposta Interativa de Voz (IVR). Por exemplo, se o usuário pressionar 4 ou diz “Vendas”, você retorna um conectar A NCCO que encaminha a ligação para o seu departamento de vendas.

O exemplo a seguir do NCCO mostra como configurar um terminal IVR:

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something"
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }
  }
]

O exemplo a seguir do NCCO mostra como usar bargeIn para permitir que um usuário interrompa um talk ação. Observe que um input ação deve acompanhar qualquer ação que tenha um bargeIn propriedade (por exemplo, talk ou stream).

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something",
    "bargeIn": true
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],	
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }	
  }
]

As seguintes opções podem ser usadas para controlar um input ação:

Configurações de entrada DTMF

Observação: Essas configurações não se aplicam se o mode está definido como asynchronous.

Configurações de reconhecimento de voz

O exemplo a seguir mostra os parâmetros enviados ao eventUrl webhook para entrada DTMF:

{
  "speech": { "results": [ ] },
  "dtmf": {
    "digits": "1234",
    "timed_out": true
  },
  "from": "15551234567",
  "to": "15557654321",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

O exemplo a seguir mostra os parâmetros enviados de volta ao eventUrl webhook para entrada de voz:

{
  "speech": {
    "recording_url": "https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab",
    "timeout_reason": "end_on_silence_timeout",
    "results": [
      {
        "confidence": "0.9405097",
        "text": "sales"
      },
      {
        "confidence": "0.70543784",
        "text": "sails"
      },
      {
        "confidence": "0.5949854",
        "text": "sale"
      }
    ]
  },
  "dtmf": {
    "digits": null,
    "timed_out": false
  },
  "from": "15551234567",
  "to": "15557654321",  
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

Parâmetros de entrada e retorno

Veja Referência sobre Webhooks para parâmetros de entrada que são retornados ao eventUrl.

Notificar

Use o notify ação para enviar uma carga personalizada para a URL do seu evento. Seu endpoint de webhook pode retornar outro NCCO que substitua o NCCO existente ou retornar uma carga vazia, o que significa que o NCCO existente continuará a ser executado.

[
  {
    "action": "notify",
    "payload": {
      "foo": "bar"
    },
    "eventUrl": [
      "https://example.com/webhooks/event"
    ],
    "eventMethod": "POST"
  }
]

Configurações de voz das instruções

Espere

Você pode usar o wait ação para adicionar um período de espera e pausar a execução do NCCO em andamento por um número especificado de segundos.

A ação é síncrona. O período de espera começa quando a ação de espera é executada no NCCO e termina após o valor de tempo limite especificado ou padrão. Nesse momento, o NCCO retoma a execução. O timeout O parâmetro é do tipo float. Os valores válidos variam de 0,1 segundo a 7.200 segundos. Valores inferiores a 0,1 assumem o valor padrão de 0,1 segundo, e valores superiores a 7.200 assumem o valor padrão de 7.200 segundos. Se não for especificado, o valor padrão é 10 segundos.

O exemplo a seguir do NCCO mostra como executar a ação de espera:

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference"
  },
  {
    "action": "wait",
    "timeout": 0.5
  },
  {
    "action": "talk",
    "text": "We will connect you when an agent is available"
  }
]

Você pode usar as seguintes opções para controlar um wait ação:

Transferência

O transfer A ação é síncrona. Você pode usá-la para transferir as partes da chamada de uma conversa atual para outra conversa já existente. A transfer essa ação encerra a conversa atual, e o NCCO da conversa de destino continua a controlar o comportamento dessa conversa. Todas as ramificações da conversa atual são transferidas para a conversa de destino, respeitando as configurações de áudio (canHear, canSpeak, mute) caso sejam fornecidos.

O exemplo a seguir do NCCO mostra como executar a ação de transferência:

[
   ...
   {
     "action": "transfer",
     "conversationId": "CON-f972836a-550f-45fa-956c-12a2ab5b7d22",
     "canHear": [ "9c132730-8c22-4760-a4dc-40502f05b444" ]
   }
   ...
]

Você pode usar as seguintes opções para controlar uma ação de transferência: