Início rápido: receber e responder SMS

Artigo
03/16/2023

Os recursos de SMS dos Serviços de Comunicação do Azure fornecem aos desenvolvedores opções para consumir eventos recebidos por SMS. Os eventos são postados na Grade de Eventos do Azure que fornece integrações prontas para uso para processar aqueles que usam webhooks, Azure Functions, conectores do Power Automate/Aplicativo Lógico e muito mais.

Depois de recebidas, as mensagens SMS podem ser processadas para responder a elas ou simplesmente registrá-las em um banco de dados para acesso futuro.

Neste Início rápido, nos concentraremos em mostrar o processamento de eventos recebidos por SMS por meio do Azure Functions usando gatilhos da Grade de Eventos e conectores sem código para o Power Automate/Aplicativos Lógicos.

O evento SMSReceived gerado quando um SMS é enviado para um número de telefone dos Serviços de Comunicação do Azure é formatado da seguinte maneira:

[{
  "id": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
  "topic": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/acse2e/providers/microsoft.communication/communicationservices/{communication-services-resource-name}",
  "subject": "/phonenumber/15555555555",
  "data": {
    "MessageId": "Incoming_20200918002745d29ebbea-3341-4466-9690-0a03af35228e",
    "From": "15555555555",
    "To": "15555555555",
    "Message": "Great to connect with Azure Communication Services events",
    "ReceivedTimestamp": "2020-09-18T00:27:45.32Z"
  },
  "eventType": "Microsoft.Communication.SMSReceived",
  "dataVersion": "1.0",
  "metadataVersion": "1",
  "eventTime": "2020-09-18T00:27:47Z"
}]

Para começar a gerar os eventos, devemos configurar a Grade de Eventos do Azure para o recurso dos Serviços de Comunicação do Azure.

Observação

O uso da Grade de Eventos do Azure gera custos adicionais. Para saber mais, confira Preço da Grade de Eventos do Azure.

Pré-requisitos

Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação. Crie um recurso dos Serviços de Comunicação.
Um número de telefone habilitado para SMS. Obter um número de telefone.
Habilite o recurso da Grade de Eventos fornecido em sua assinatura. Veja instruções.

O Grade de Eventos dá suporte imediato ao Azure Functions, facilitando a configuração de um ouvinte de eventos sem a necessidade de lidar com a complexidade de analisar cabeçalhos ou depurar webhooks. Usando o gatilho pronto para uso, podemos configurar uma Função do Azure que é executada sempre que um evento que corresponde ao gatilho é detectado. Neste documento, nos concentramos nos gatilhos recebidos por SMS.

Configurando nosso ambiente local

Usando o Visual Studio Code, instale a extensão do Azure Functions.
Com a extensão, crie uma Função do Azure seguindo estas instruções.

Configure a função com as seguintes instruções:
- Linguagem: TypeScript
- Modelo: gatilho da Grade de Eventos do Azure
- Nome da função: definido pelo usuário
Depois de criado, você verá uma função criada em seu diretório da seguinte maneira:
```
import { AzureFunction, Context } from "@azure/functions"

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
    context.log(eventGridEvent);

};

export default eventGridTrigger;
```

Configurar Função do Azure para receber eventos de SMS

Configure a Função do Azure para analisar os valores do evento, como quem o enviou, para qual número e qual era a mensagem.


import { AzureFunction, Context } from "@azure/functions"

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
   context.log(eventGridEvent);
   const to = eventGridEvent['data']['to'];
   const from = eventGridEvent['data']['from'];
   const message = eventGridEvent['data']['message'];

};

export default eventGridTrigger;

Nesse momento, você conseguiu receber um SMS por meio de eventos. Agora, as possibilidades do que fazer com esse evento variam desde apenas registrá-lo até respondê-lo. Na próxima seção, nos concentramos em responder a esse SMS que recebemos. Se você não quiser responder ao SMS, pule para a próxima seção sobre como executar a função localmente.

Respondendo ao SMS

Para responder ao SMS recebido, usamos os recursos de SMS do Serviço de Comunicação do Azure para enviar SMS. Começamos invocando o SmsClient e inicializando-o com o connection string do nosso recurso. É possível colar a cadeia de conexão diretamente no código ou colocá-la dentro de seu arquivo local.settings.json em seu diretório da Função do Azure em valores.


{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "ACS_CONNECTION_STRING": "<<CONNECTION STRING>>"
  }
}

Em seguida, escrevemos um SMS para enviar com base nos valores to e from do evento que recebemos.

import { AzureFunction, Context } from "@azure/functions"
import { SmsClient } from "@azure/communication-sms";

const connectionString = process.env.ACS_CONNECTION_STRING; //Replace with your connection string

const eventGridTrigger: AzureFunction = async function (context: Context, eventGridEvent: any): Promise<void> {
    context.log(eventGridEvent);
    const to = eventGridEvent['data']['to'];
    const from = eventGridEvent['data']['from'];
    const message = eventGridEvent['data']['message'];

    const smsClient = new SmsClient(connectionString);

    const sendResults = await smsClient.send({
        from: to,
        to: [from],
        message: "Message received successfully. Will respond shortly."
    });

};

export default eventGridTrigger;

A partir daqui, as possibilidades são infinitas. Desde responder a uma mensagem com uma resposta predefinida, até adicionar um bot ou simplesmente armazenar respostas, você pode adaptar o código na última etapa para fazer isso.

Execução local

Para executar a função localmente, pressione F5 no Visual Studio Code. Usamos o ngrok para conectar nossa Função do Azure em execução local com a Grade de Eventos do Azure.

Assim que a função estiver em execução, configuramos o ngrok. (Você precisa baixar o ngrok para seu ambiente.)
```
ngrok http 7071
```
Copie o link ngrok fornecido onde sua função está sendo executada.
Configure eventos SMS por meio da Grade de Eventos no recurso dos Serviços de Comunicação do Azure. Fazemos isso usando a CLI do Azure. Você precisa da ID de recurso para o recurso dos Serviços de Comunicação do Azure encontrado no portal do Azure. (A ID do recurso será algo como: /subscriptions/<<AZURE SUBSCRIPTION ID>>/resourceGroups/<<RESOURCE GROUP NAME>>/providers/Microsoft.Communication/CommunicationServices/<<RESOURCE NAME>>)
```
az eventgrid event-subscription create --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type webhook --endpoint "<<NGROK URL>> " --source-resource-id "<<RESOURCE_ID>>"  --included-event-types Microsoft.Communication.SMSReceived 
```
Agora que tudo está conectado, teste o fluxo enviando um SMS para o número de telefone que você tem no recurso dos Serviços de Comunicação do Azure. Você verá os logs do console em seu terminal onde a função está sendo executada. Se você adicionou o código para responder ao SMS, deverá ver a mensagem de texto entregue de volta para você.

Implantar no Azure

Para implantar a Função do Azure no Azure, siga estas instruções. Depois de implantado, configuramos a Grade de Eventos para o recurso dos Serviços de Comunicação do Azure. Com o URL da Função do Azure que foi implantada (URL encontrado no portal do Azure na função), executamos o seguinte comando:


az eventgrid event-subscription update --name "<<EVENT_SUBSCRIPTION_NAME>>" --endpoint-type azurefunction --endpoint "<<AZ FUNCTION URL>> " --source-resource-id "<<RESOURCE_ID>>"

Como estamos atualizando a assinatura do evento que criamos para teste local, use o mesmo nome da assinatura do evento usado acima.

Teste enviando um SMS para o número de telefone adquirido por meio do recurso dos Serviços de Comunicação do Azure.

Os Aplicativos Lógicos e o Power Automate fornecem conectores prontos para uso para ajudar a lidar com eventos gerados pelos Serviços de Comunicação do Azure por meio da Grade de Eventos. Os Aplicativos Lógicos e o Power Automate fornecem o mesmo conjunto de conectores. Cabe a você decidir o que prefere, leia sobre as diferenças entre os serviços para tomar sua decisão.

Manipulando eventos com o conector da Grade de Eventos

Comece criando um novo fluxo em seu ambiente preferido. Escolha o gatilho When a resource event occurs para começar.
Agora, vamos configurá-lo. O conector exige que você forneça uma assinatura que deseja usar. (Deve ser a mesma assinatura em que está o recurso dos Serviços de Comunicação do Azure). Especifique o tipo de recurso. Nesse caso, escolha Microsoft.Communication.CommunicationServices. Em seguida, você precisará fornecer um nome de recurso para o recurso dos Serviços de Comunicação do Azure ao qual deseja que ele se conecte. Por fim, precisamos escolher os tipos de evento que desejamos receber, nesse caso: Microsoft.Communication.SMSReceived.

O conector configura automaticamente a assinatura do evento em seu nome e configura os eventos que deseja receber.

Para facilitar nossas vidas posteriormente, adicione um Parse JSON connector para processar a resposta proveniente do conector da Grade de Eventos. Configure o conector para pegar o objeto Body do conector da Grade de Eventos e combiná-lo com o esquema esperado para o evento:

Esquema de exemplo (abra para ver)


    {
        "properties": {
            "data": {
                "properties": {
                    "From": {
                        "type": "string"
                    },
                    "Message": {
                        "type": "string"
                    },
                    "MessageId": {
                        "type": "string"
                    },
                    "ReceivedTimestamp": {
                        "type": "string"
                    },
                    "To": {
                        "type": "string"
                    }
                },
                "type": "object"
            },
            "dataVersion": {
                "type": "string"
            },
            "eventTime": {
                "type": "string"
            },
            "eventType": {
                "type": "string"
            },
            "id": {
                "type": "string"
            },
            "metadataVersion": {
                "type": "string"
            },
            "subject": {
                "type": "string"
            },
            "topic": {
                "type": "string"
            }
        },
        "type": "object"
    }

Captura de tela do conector Analisar JSON.

Nesse momento, você lidou com êxito com o evento SMS. Você então tem várias opções do que fazer com ele, desde registrar o evento até responder ao SMS. No contexto deste documento, mostraremos como responder a ele. Continue lendo para saber as etapas para responder ao SMS.

Respondendo ao SMS

Comece adicionando o conector SMS em nosso fluxo e configurando-o com as informações do recurso dos Serviços de Comunicação do Azure. Ele permite que o conector acesse o recurso e envie o SMS em nosso nome. Você precisa do connection string para o seu recurso.
Em seguida, configuramos o conector com as informações do remetente e destinatário. Usamos as informações do evento que recebemos para preenchê-las. Toque nos números to e from para enviar um SMS de volta ao remetente original. Por fim, adicione uma mensagem.

Agora, você pode salvar o fluxo e testá-lo enviando um SMS para o número de telefone associado ao recurso dos Serviços de Comunicação do Azure. Você receberá de volta uma mensagem de texto.

A partir daqui, as possibilidades são infinitas. Desde responder a uma mensagem com uma resposta predefinida até adicionar um bot ou simplesmente armazenar respostas, você pode adicionar mais lógica ao fluxo.

Limpar os recursos

Se quiser limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir o grupo de recursos também exclui todos os recursos associados a ele. Saiba mais sobre como limpar recursos.

Verificação por chamada gratuita

Se você tiver um novo número de chamada gratuita e quiser enviar um alto volume de mensagens SMS ou enviar mensagens SMS para números de telefone canadenses, acesse aqui para saber como verificar seu número de chamada gratuita.

Próximas etapas

Neste início rápido, você aprendeu a enviar mensagens SMS usando os Serviços de Comunicação.

Enviar SMS

Tipos de número de telefone

Saiba mais sobre SMS

Compartilhar via

Início rápido: receber e responder SMS

Pré-requisitos

Configurando nosso ambiente local

Configurar Função do Azure para receber eventos de SMS

Respondendo ao SMS

Execução local

Implantar no Azure

Manipulando eventos com o conector da Grade de Eventos

Respondendo ao SMS

Limpar os recursos

Verificação por chamada gratuita

Próximas etapas

Comentários

Recursos adicionais