API para o SMS Gateway
É possível controlar o comportamento do SMS Gateway e o fluxo de uma sessão SMS, trocando ações e variáveis de estado com o serviço IBM Watson™ Assistant. As tags de ação iniciam ações que o SMS Gateway toma durante uma sessão de conversa, e variáveis de estado são enviadas pelo SMS Gateway para indicar características da sessão.
Tags de ação
Para iniciar ações no SMS Gateway, é possível definir tags de ação em um nó de diálogo do Watson Assistant no formato JSON na propriedade output. Para cada ação, defina uma propriedade smsAction, que contém duas partes:
uma propriedade de
comando e uma propriedade de parâmetro opcional, onde você pode definir atributos para comandos que os requerem.
Por exemplo, quando um nó que contém a seguinte ação é acionado, ele configura o tempo limite da sessão para 200 segundos.
{
"output": {
"smsAction": {
"command": "setSessionTimeoutCount",
"parameters":{
"count": 200
}
}
}
}
Quando um nó contendo smsActSendMedia é acionado, um sistema de mensagens MMS é ativado.
{
"output": {
"smsAction": {
"command": "smsActSendMedia",
"parameters":{
"mediaURL": [
"https://exampleonly.com/media/l4JyRqcDU93S334KQ/first.gif",
"https://exampleonly.com/media/tK9wGsGc72LcznCSeU/second.gif"
]
}
}
}
}
A tabela a seguir lista as ações que podem ser especificadas no diálogo Watson Assistant e qualquer atributo que pode ser definido para cada ação.
| Comando de Ação | Descrição | Atributos |
|---|---|---|
setSessionTimeoutCount |
Atualiza o tempo limite da sessão | count: Tempo em segundos |
smsActForceNoInputTurn |
Força um novo turno na conversa, sem esperar pela entrada do usuário. O SMS Gateway envia uma solicitação de mensagem com smsNoInputTurn no campo de texto, para que seja possível mapear essa solicitação para uma intenção no diálogo. |
Nenhuma |
smsActSetConversationConfig |
Aplica um conjunto de parâmetros para configurar uma área de trabalho do Watson Assistant ou mecanismo de orquestração de serviço. Saiba mais em Configurando dinamicamente o serviço Watson Assistant ou mecanismo de orquestração de serviço. | Todos os parâmetros a seguir são suportados. Para obter mais informações, consulte Propriedades de configuração avançadas JSON para SMS Gateway.
tokenServiceProviderURL
|
terminateSession |
Finaliza a sessão associada | N/D |
smsActSendMedia |
Ativa o sistema de mensagens MMS | mediaURL: especifica uma matriz JSON de URLs de mídia acessíveis publicamente que são enviadas para o usuário. |
Variáveis de estado enviadas pelo SMS Gateway
Para indicar uma mudança de estado na sessão SMS, o SMS Gateway envia variáveis de contexto de cada solicitação de mensagem para o Watson Assistant.
Como o diálogo do Watson Assistant é stateless, todo estado é mantido no SMS Gateway entre trocas com o Watson Assistant. Isso significa que para cada turno do Watson Assistant dentro de uma sessão de bate-papo, a seção context é
passada para o Watson Assistant, processada ou atualizada pelo diálogo e recebida de volta do Watson Assistant.
Por exemplo, para um turno básico na sessão SMS que usa apenas valores necessários, o SMS Gateway envia o seguinte objeto de contexto.
{
"context": {
"smsTenantPhoneNumber": "+12345556789",
"smsUserPhoneNumber": "+18765554321",
"smsSessionID": "a23de67h-e527-40d5-a867-5c0ce9e72d0d"
}
}
As seguintes variáveis de estado são enviadas do SMS Gateway na solicitação de mensagem. Os valores smsTenantPhoneNumber, smsUserPhoneNumber, smsUserData e smsSessionTimeoutCount são obtidos diretamente
da API de REST da sessão.
| Variável de Estado | Descrição |
|---|---|
smsTenantPhoneNumber |
O número de telefone do locatário do SMS Gateway para o qual o usuário está enviando mensagens. |
smsUserPhoneNumber |
O número de telefone do usuário que está trocando mensagens com SMS Gateway. |
smsUserData |
Os dados no formato JSON a serem passados literalmente para o mecanismo de orquestração de serviço ou serviço Watson Assistant. Essa variável é enviada apenas se a sessão é iniciada a partir do locatário do SMS Gateway e os dados são enviados por meio da API de REST. |
smsSessionTimeoutCount |
O valor de tempo limite da sessão. Essa variável é enviada apenas se o valor de tempo limite é definido por meio da API de REST. |
smsError |
Quando o SMS Gateway não envia uma mensagem SMS, essa variável contém detalhes sobre o erro que ocorreu. |
smsSessionID |
O GUID para a sessão relacionada do SMS Gateway. |
smsMedia |
A arraylist do mediaURL e a mediaContentType correspondente. Essa variável de contexto é limpa no final de cada turno da conversa. |
Palavras-chave de texto
Alguns eventos acionam o SMS Gateway para enviar uma palavra-chave de texto na solicitação de mensagem para o Watson Assistant. Você pode usar essas palavras-chave de texto para processamento adicional em um mecanismo de orquestração de serviço ou análise.
A tabela a seguir lista o valor de texto exato enviado pelo SMS Gateway e o evento que o aciona.
| Valor de texto | Evento |
|---|---|
smsError |
Enviado se um erro ocorre ao enviar uma mensagem SMS de saída para o provedor SMS. |
smsResponseTimeout |
Enviado se ocorre um tempo limite de sessão quando o usuário não responde no tempo configurado por smsSessionTimeoutCount. |
O conjunto de variáveis no diálogo do Watson Assistant
É possível configurar as variáveis de estado a seguir no diálogo do Watson Assistant para modificar o comportamento do SMS Gateway. Caso uma variável que possui uma variável de ambiente de configuração relacionada não seja configurada, o valor da variável de ambiente relacionada será utilizado.
| Nome da variável de estado | Valor esperado | Descrição | Variável de ambiente relacionada |
|---|---|---|---|
smsConversationResponseTimeout |
Tempo em ms | A quantia de tempo em milissegundos que o SMS Gateway aguarda para receber uma resposta do serviço Watson Assistant. Se o tempo é excedido, o SMS Gateway tenta novamente contatar o serviço Watson Assistant. Se ainda assim o serviço não puder ser atingido, a resposta de SMS falhará. Versão 1.0.0.5a e mais recente. | WATSON_CONVERSATION_READ_TIMEOUT |