Tudo o que Você Precisa Saber Sobre a Utilização de Subcontas na Twilio

Tempo de leitura: 6 minutos

February 24, 2021

Escrito por

Josh Siverson

Twilion

Revisado por

Ashley Boucher

Twilion

Liz Moy

Twilion

Tudo o que Você Precisa Saber Sobre a Utilização de Subcontas na Twilio

Este post vai te falar sobre os benefícios de se usar subcontas e como enviar mensagens através delas. Elas te permitem separar seu uso, números e configurações enquanto você compartilha os gastos com sua conta principal. Elas são uma ótima maneira de segmentar seu uso na Twilio.

Abaixo estão os principais itens que vamos ver neste post:

Requisitos Técnicos
O que são subcontas Twilio e por que você deveria usá-las?
Usando subcontas para enviar uma Mensagem

Requisitos Técnicos

Uma conta gratuita na Twilio – cadastre-se neste link, você vai conseguir $10 em créditos quando atualizar a conta.
Um número de telefone Twilio.
Um número de celular verificado (para receber SMS).
Familiaridade com o envio de chamadas de API REST. Aqui vão algumas dicas úteis de como rodar o cURL n o bash ou zsh, ou você pode usar uma ferramenta como o Postman.

O que são subcontas Twilio e por que você deveria usá-las?

Subcontas são containers que separam recursos que pertencem ao projeto principal no console da Twilio. Por exemplo; considere a companhia fictícia Owlie Notifications. Ela oferece uma plataforma SaaS que dá aos usuários a habilidade de fazer chamadas. A Owlie Notifications tem aproximadamente 50 clientes.

A Owlie Notifications tem duas opções quando criam sua estrutura de contas na Twilio:

Crie uma conta Twilio, que está atrelada a um identificador chamado de Account SID, que é único nas contas, e sempre está prefixada com “AC”. Sempre que a Owlie Notifications fizer uma chamada de API, eles vão usar o Account SID para essa conta na chamada. Para exemplificar, vamos dizer que o Account SID seja AC123.
Criar uma conta Twilio (Account SID = AC123, ou seja, a conta pai) da mesma maneira do que a sugerida na opção 1, no entanto, eles também vão criar uma subconta para cada um dos seus 50 clientes (50 subcontas). Cada uma dessas subcontas vai ter seu Account SID único. Então, quando a Owlie Notifications fizer uma chamada na API para um cliente, eles vão usar o Account SID apropriado, ao invés do Account SID da conta principal.

Aqui está o porquê de se ir com a opção número dois é a melhor opção.

Benefícios chave das subcontas

Você pode segmentar o processo de pagamento

Se a Owlie Notifications escolhesse não usar subcontas, eles precisariam gravar todo o uso de cada cliente, o que traz um trabalho adicional e deixa margem para erros. Por que as subcontas agem como containers, você pode usar a API Twilio Usage para pegar dados de pagamento específicos para a subconta, reduzindo a lógica de negócio necessária para implementar o rastreio individual dos clientes.

Permite o provisionamento de recursos

Subcontas permitem com que recursos (como números de celular) sejam adicionados a subcontas específicas. Uma consideração é a de que a maioria dos recursos podem pertencer a apenas uma subconta por vez. Isso pode ser um pouco difícil de lidar se você estiver constantemente movendo números entre contas. Por exemplo, você vai precisar lidar com essa lógica se você fechar uma subconta, mas quiser manter o número de telefone. Por sorte, a Twilio permite mover números de telefone entre contas.

Te dá controle adicional sobre múltiplas contas do mesmo projeto: Com subcontas, você pode suspender, fechar e reativar subcontas baseado nas necessidades do cliente.

Considerações antes de migrar para subcontas

Para clientes usanda Twilio conseguirem enviar mensagens, a Twilio vai te ajudar a gerenciar a saída dos seus clientes (opt-out), como quando usuário final responder PARAR a mensagens. A Twilio mantém essa lista de pessoas que escolheram sair no nível da conta.

Isso significa que se um usuário final responder STOP (parar) para um número de telefone, e este número for movido de um projeto para uma subconta, que tem um Account SID único, esse mapeamento é quebrado. Se você não tiver rastreando as saídas, comece agora para garantir que você tem a lista mais atualizada de inscritos.

Usando subcontas para enviar uma Mensagem

Você deve estar se perguntando: “E se eu já não estiver usando subcontas? O quão difícil é fazer a migração?”

Imagine que a Owlie Notifications tenha usando uma conta única para todos os 50 clientes. Eles agora têm clientes que querem enviar mensagens de SMS. Abaixo estão os passos que a Owlie Notifications provavelmente vai precisar seguir:

Você vai usar a API REST de subcontas para fazer isso programaticamente, no entanto, você pode escolher usar nossos SDKs para servidor se preferir.

Primeiro, entre no Console da Twilio. Você vai ver Account SID e Auth Token designados para sua conta no dashboard:

tela com informações da Account SID e Auth Token

Para os próximos exemplos, você vai usar o Account SID e Auth Token para a conta Twilio que você acabou de fazer ou copiou. Não se esqueça de substituí-los em todos os lugares abaixo.

Crie uma subconta

Vamos continuar com os clientes da Owlie Notifications (Falcon Flights) e criar uma subconta para eles.

Chamada

Do seu terminal ou terminal de comando, rode o seguinte comando para fazer a chamada, tomando o cuidado para substituir os valores dos marcadores com seu Account SID e Auth Token.

curl -X POST https://api.twilio.com/2010-04-01/Accounts.json \
--data-urlencode "FriendlyName=FalconFlights
" \
-u <INSIRA O ACCOUNT SID DA CONTA PAI>:<INSIRA AUTH TOKEN DA CONTA PAI>

Resposta

Depois de rodar o comando, você vai receber uma resposta como essa:

{
   "status": "active",
   "date_updated": "Wed, 17 Feb 2021 15:12:01 +0000",
   "auth_token": "ACxxxxx",
   "friendly_name": "FalconFlights",
   "owner_account_sid": "ACxxxx",
   "uri": "/2010-04-01/Accounts/ACxxx.json",
   "sid": "ACxxx
",
   "date_created": "Wed, 17 Feb 2021 15:12:01 +0000",
   "type": "Full",
   "subresource_uris": {
...
   }
}

Essa resposta inclui algumas peças chave de informação.

Tem uma conta nova chamada FalconFlights que tem seu Account SID único e Auth Token.

O owner_account_sid deve ser o mesmo do seu projeto pai (Owlie Notifications).

Por favor guarde este Account SID e Auth Token já que você vai usá-los depois.

Transfira um número de telefone

Mais cedo, eu mencionei o caso onde você pode querer transferir um número de telefone. Aqui está como fazer isso. Se você não tiver um número de telefone Twilio, você pode comprar um pelo Console da Twilio ou API REST.

Para começar a transferir seu número de telefone Twilio entre sua conta pai e subconta, navegue até a seção de Números Ativos (Active Numbers) no Console. Clique em um número para ver uma tela com as opções de configuração.

É aqui que você encontra seu Phone Number SID (PNxxx).

como localizar o SDI do número de telefone

Chamada

É importante garantir que você está usando o Account SID da conta pai no cabeçalho, já que a conta pai é dona do número de telefone.

Rode o comando em seu terminal:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/<INSERT PARENT ACCOUNT SID>/IncomingPhoneNumbers/<INSIRA SDI DO NÚMERO DE TELEFONE>.json \
--data-urlencode "AccountSid=<INSIRA SDI SUBCOUNTA>" \
-u <INSIRA O ACCOUNT SID DA CONTA PAI>:<INSIRA AUTH TOKEN DA CONTA PAI>

Nota que ao mover números de telefone para uma outra conta, a URL de Voz e SMS será preservada.

Resposta

{
    "sid": "PNxxx",
    "account_sid": "ACxxx",
    "friendly_name": "(415) 874-0103",
    "phone_number": "+14158740103",
    "voice_url": "https://demo.twilio.com/welcome/voice/",
    "voice_method": "POST",
    "voice_fallback_url": null,
    "voice_fallback_method": "POST",
    "voice_caller_id_lookup": false,
    "date_created": "Wed, 17 Feb 2021 15:17:28 +0000",
    "date_updated": "Wed, 17 Feb 2021 15:23:39 +0000",
    "sms_url": "https://demo.twilio.com/welcome/sms/reply",
    "sms_method": "POST",
    "sms_fallback_url": "",
    "sms_fallback_method": "POST",
    "address_requirements": "none",
    "beta": false,
    "capabilities": {
        "voice": true,
        "sms": true,
        "mms": true,
        "fax": true
    },
    "voice_receive_mode": "voice",
    "status_callback": "",
    "status_callback_method": "POST",
    "api_version": "2010-04-01",
    "voice_application_sid": null,
    "sms_application_sid": "",
    "origin": "twilio",
    "trunk_sid": null,
    "emergency_status": "Inactive",
    "emergency_address_sid": null,
    "address_sid": null,
    "identity_sid": null,
    "bundle_sid": null,
    "uri": "/2010-04-01/Accounts/AC1bcc67e32e161e04aaacc159b2e86601/IncomingPhoneNumbers/PNd7c52583c2ffabfe2a05a165e48e3e68.json",
    "status": "in-use"
}

Crie um Serviço de Mensagens

Crie um Serviço de Mensagens em sua conta recém criada. Um Serviço de Mensagens é um recurso que pode agir como um container para seus números de telefone, e fornece software que facilita sua vida ao enviar mensagens em grande escala. Para esse pedido, você vai usar o Account SID e Auth Token associados à sua subconta.

Chamada

curl -X POST https://messaging.twilio.com/v1/Services \
--data-urlencode "FriendlyName=falconFlightNotifications" \
-u <INSIRA SID DA SUBCONTA>:<INSIRA AUTH TOKEN DA SUBCONTA>

Resposta

A resposta vai te fornecer um Messaging Service SID (MGxxxx). Você vai usar isso nos próximos passos, então guarde isso.

Você vai perceber alguns atributos diferentes em seu objeto de resposta. Se você quiser aprender mais sobre todas as funcionalidades de um Serviço de Mensagens, verifique a documentação do nosso Serviço de Mensagens.

{
   "fallback_method": "POST",
   "fallback_to_long_code": true,
   "date_updated": "2021-02-17T15:28:03Z",
   "synchronous_validation": false,
   "sticky_sender": true,
   "inbound_method": "POST",
   "friendly_name": "falconFlightNotifications",
   "mms_converter": true,
   "validity_period": 14400,
   "account_sid": "ACxxx",
   "fallback_url": null,
   "inbound_request_url": null,
   "url": "https://messaging.twilio.com/v1/Services/MGa91155a0d582afdde110a606465d1daa",
   "sid": "MGxxxx",
   "date_created": "2021-02-17T15:28:03Z",
   "smart_encoding": true,
   "scan_message_content": "inherit",
   "area_code_geomatch": true,
   "status_callback": null,
   "links": {
      ...
   }
}

Adicione um Número de Telefone ao Serviço de Mensagens

Agora que você tem um Serviço de Mensagens, você pode usar a API do Serviço para adicionar seu número de telefone.

Chamada

curl -X POST https://messaging.twilio.com/v1/Services/<INSERT YOUR MESSAGING SERVICE SID/PhoneNumbers \
--data-urlencode "PhoneNumberSid=<INSIRA SDI DO NÚMERO DE TELEFONE>" \
-u <INSIRA SID DA SUBCONTA>:<INSIRA AUTH TOKEN DA SUBCONTA>

Resposta

Agora você adicionou com sucesso o número de telefone ao seu Serviço de Mensagens.

{
   "phone_number": "+14158740103",
   "date_updated": "2021-02-17T15:30:47Z",
   "capabilities": [
       "MMS",
       "SMS",
       "Voice"
   ],
   "account_sid": "AC1bcc67e32e161e04aaacc159b2e86601",
   "url": "https://messaging.twilio.com/v1/Services/MGxxx/PhoneNumbers/PNxxx",
   "country_code": "US",
   "sid": "PNxxxx",
   "date_created": "2021-02-17T15:30:47Z",
   "service_sid": "MGxxxx"
}

Enviando uma Mensagem

Agora que você tem uma nova subconta, um Serviço de Mensagens com um número de telefone te permite enviar uma mensagem!

Para enviar uma mensagem pelo Serviço de Mensagens, use o Messaging Service SID (MGxxxx) na sua chamada.

Certifique-se de que o número de telefone To é verificado. Se seu número não for verificado, você pode adicionar um número de telefone verificado pelo Console da Twilio.

Chamada

curl -X POST https://api.twilio.com/2010-04-01/Accounts/<INSERT YOUR SUBACCOUNT SID>/Messages.json \
--data-urlencode "Body=Olá" \
--data-urlencode "From=<INSIRA O MESSAGING SERVICE SID>
" \
--data-urlencode "To=<INSIRA SEU TELEFONE NO FORMATO E.164>" \
-u <INSIRA SID DA SUBCONTA>:<INSIRA AUTH TOKEN DA SUBCONTA>

Resposta

{
   "sid": "SMb319786dcd44433b905d0e8acd2b33f3",
   "date_created": "Wed, 17 Feb 2021 15:39:56 +0000",
   "date_updated": "Wed, 17 Feb 2021 15:39:56 +0000",
   "date_sent": null,
   "account_sid": "ACxxx",
   "to": "<SEU NUMERO>",
   "from": null,
   "messaging_service_sid": "MGxxx",
   "body": "Olá",
   "status": "accepted",
   "num_segments": "0",
   "num_media": "0",
   "direction": "outbound-api",
   "api_version": "2010-04-01",
   "price": null,
   "price_unit": null,
   "error_code": null,
   "error_message": null,
   "uri": "/2010-04-01/Accounts/ACxxx/Messages/SMb319786dcd44433b905d0e8acd2b33f3.json",
   "subresource_uris": {
       "media": "/2010-04-01/Accounts/ACxxx/Messages/SMb319786dcd44433b905d0e8acd2b33f3/Media.json"
   }
}

Quando tiver sucesso, você deve receber um texto como o abaixo:

Sensacional, funcionou!

Conclusão: subcontas são poderosas

Vamos recapitular tudo o que você fez:

Criou uma subconta
Transferiu um número de telefone da conta pai para a subconta
Criou um Serviço de Mensagens em sua subconta
Adicionou seu número de telefone ao Serviço de Mensagens
Enviou uma mensagem pelo seu Serviço de Mensagens em sua subconta

Espero que você tenha percebido o poder das subcontas! Este artigo apenas arranhou a superfície. Se você gostou deste post, você pode se interessar também em: