Tudo o que você precisa saber sobre o uso 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

Este artigo explicará os benefícios das subcontas e como enviar mensagens através delas. As subcontas permitem que você separe seu uso, números e configurações enquanto compartilha um saldo com sua conta principal. São uma ótima maneira de segmentar seu uso da Twilio.  

Estes são os principais itens que abordaremos neste artigo:

  • Requisitos técnicos
  • O que são as subcontas da Twilio e por que você deveria usá-las?
  • Como usar subcontas para enviar uma mensagem

 

Requisitos técnicos

  • Uma conta gratuita da Twilio: cadastre-se por este link e você receberá um crédito extra de US$ 10 quando fizer o upgrade.
  • Um número de telefone da Twilio.
  • Um números de celular verificado (para receber mensagens SMS).
  • Familiaridade com o envio de solicitações de API REST. Aqui estão dicas úteis sobre como executar um cURL a partir do bash ou zsh ou você pode usar uma ferramenta como Postman.

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

Subcontas são contêineres que separam recursos que pertencem a um projeto Twilio (principal). Por exemplo, considere a empresa fictícia Owlie Notifications. A Owlie Notifications oferece uma plataforma SaaS que permite que os clientes façam chamadas. A empresa tem cerca de 50 clientes.

Ao criar sua estrutura de conta da Twilio, a Owlie Notifications tem duas opções:

  1. Criar uma conta Twilio vinculada a um identificador chamado SID da conta, que é exclusivo de sua conta e sempre possui o prefixo "AC". Sempre que a Owlie Notifications fizer uma solicitação de API, ela usará o SID da conta nessa solicitação. Por exemplo, digamos que o SID da conta seja AC123.
  2. Além de criar uma conta Twilio (SID da conta = AC123, chamada de conta principal) da mesma maneira sugerida na opção um, criar também uma subconta para cada um de seus 50 clientes (ou seja, 50 subcontas). Cada uma das 50 subcontas terá seu próprio SID de conta exclusivo. Assim, quando a Owlie Notifications fizer uma solicitação de API para um cliente, ela usará o SID da respectiva subconta em vez do SID da conta principal.

É por isso que a segunda opção é a escolha ideal.

Principais benefícios das subcontas

Você pode segmentar o processo de faturamento 

Se a Owlie Notifications optar por não usar subcontas, ela terá que rastrear o uso de cada cliente por conta própria, resultando em mais trabalho e aumentando a possibilidade de erros. Como as subcontas funcionam como contêineres, você pode utilizar a API Twilio Usage para obter dados de faturamento específicos de uma subconta, reduzindo assim a lógica de negócios necessária para implementar o rastreamento individual de clientes.

Permite o provisionamento de recursos

As subcontas permitem que recursos (como números de telefone) sejam adicionados à subconta específica. Uma consideração é que a maioria dos recursos pode pertencer a apenas uma subconta de cada vez. Isso pode ser complicado se você estiver constantemente movendo números entre as contas. Por exemplo, você precisará lidar com essa lógica se fechar uma subconta, mas quiser manter o número de telefone. Felizmente, a Twilio permite mover números de telefone entre contas.

Oferece controle adicional sobre várias contas do mesmo projeto: Com as subcontas, você pode suspender, fechar e reativar subcontas com base nas necessidades de seus clientes.

Considerações antes de migrar para subcontas

Para os clientes que usam a Twilio para enviar mensagens, a Twilio ajudará a gerenciar o opt-out de clientes, por exemplo, quando um usuário final responde a uma mensagem com PARAR. A Twilio mantém essa lista de opt-out no nível da conta.

Isso significa que, se um usuário final respondeu PARAR a um número de telefone e esse número for movido de um projeto para uma subconta, que tem um SID de conta exclusivo, esse mapeamento de opt-out será interrompido. Caso você não esteja rastreando opt-outs, comece agora para ter a lista mais atualizada de assinantes.

Como usar subcontas para enviar uma mensagem

Você pode estar pensando: "E se eu ainda não estiver usando subcontas? É muito difícil migrar?"

Imagine que a Owlie Notifications esteja usando uma única conta para todos os 50 clientes. Agora, eles têm clientes que desejam enviar mensagens SMS. Estas são as etapas que a Owlie Notifications provavelmente precisará seguir:

Você usará a API REST das subcontas para fazer isso de forma programática, mas poderá optar por usar as bibliotecas auxiliares no servidor, se preferir.

Primeiro, faça login no seu console da Twilio. No dashboard, você verá o SID da conta e o Token de autenticação atribuídos à sua conta:

SID da conta da Twilio e token de autenticação no console

Nos exemplos a seguir, você usará o SID da conta e o token de autenticação da conta Twilio que acabou de criar ou copiar. Não se esqueça de substituí-los em todos os espaços reservados abaixo.

Crie uma subconta

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

Solicitação

No seu terminal ou prompt de comando, execute o seguinte comando para fazer a solicitação, tomando cuidado para substituir os valores nos espaços reservados pelo SID da conta principal e token de autenticação.

curl -X POST https://api.twilio.com/2010-04-01/Accounts.json \
--data-urlencode "FriendlyName=FalconFlights
" \
-u <INSERT YOUR PARENT ACCOUNT SID>:<INSERT YOUR PARENT AUTH TOKEN>

Resposta

Depois de executar o comando, você receberá uma resposta como esta:

{
   "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": {
...
   }
}

Esta resposta contém algumas informações importantes.

Há uma nova conta chamada FalconFlights que tem seus próprios SID e token de autenticação.

O owner_account_sid deve corresponder ao SID da conta (principal) do projeto (Owlie Notifications).

Mantenha um registro do SID da subconta e do token de autenticação, pois eles serão usados posteriormente.

Transferir um número de telefone

Anteriormente, mencionamos o caso em que você pode querer transferir um número de telefone. Descubra como fazer isso. Se você não tiver um número de telefone Twilio, poderá comprar um pelo console da Twilio ou pela API REST.

Para começar a transferir seu número de telefone Twilio entre sua conta principal e uma subconta, vá até a seção Números ativos do console. Clique em um número para visualizar as opções de configuração.

Lá você encontrará o SID do número de telefone (PNxxx).

Como localizar um identificador de número de telefone na Twilio

Solicitação

É importante que você use o SID da conta principal em seus cabeçalhos, pois a conta principal possui o número de telefone.

Execute o seguinte comando no seu terminal:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/<INSERT PARENT ACCOUNT SID>/IncomingPhoneNumbers/<INSERT PHONE NUMBER SID>.json \
--data-urlencode "AccountSid=<INSERT SUBACCOUNT SID>" \
-u <INSERT YOUR PARENT ACCOUNT SID>:<INSERT YOUR PARENT AUTH TOKEN>

Observe que, ao mover números de telefone para outra conta, o URL do Voice e do SMS será preservado.

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"
}

Criar um serviço de mensagens

Crie um serviço de mensagens na subconta recém-criada. Um serviço de mensagens é um recurso que pode servir como um contêiner de seus números de telefone e oferece um software que facilita o envio de mensagens em escala.

Para esta solicitação, você usará o SID da conta e o token de autenticação associados à subconta.

Solicitação

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

Resposta

A resposta fornecerá um SID do serviço de mensagens (MGxxxx). Ele será usado nas próximas etapas, então mantenha-o à mão.

Você notará alguns atributos diferentes em seu objeto de resposta. Se quiser saber mais sobre todos os recursos em um serviço de mensagens, consulte a documentação do 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": {
      ...
   }
}

Adicionar um número de telefone a um serviço de mensagens

Agora que você tem um serviço de mensagens, pode usar a API de serviços para adicionar seu número de telefone ao serviço de mensagens.

Solicitação

curl -X POST https://messaging.twilio.com/v1/Services/<INSERT YOUR MESSAGING SERVICE SID/PhoneNumbers \
--data-urlencode "PhoneNumberSid=<INSERT PHONE NUMBER SID>" \
-u <INSERT YOUR SUBACCOUNT SID>:<INSERT YOUR SUBACCOUNT AUTH TOKEN>

Resposta

Você adicionou com sucesso o número de telefone ao 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"
}

Enviar uma mensagem

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

Para enviar uma mensagem através desse serviço, use o SID do serviço de mensagens (MGxxx) em sua solicitação.

Confira se o número de telefone em To foi verificado. Caso não tenha sido, você poderá adicionar um número de telefone verificado através do console da Twilio.

Solicitação

curl -X POST https://api.twilio.com/2010-04-01/Accounts/<INSERT YOUR SUBACCOUNT SID>/Messages.json \
--data-urlencode "Body=Hi there" \
--data-urlencode "From=<INSERT YOUR MESSAGING SERVICE SID>
" \
--data-urlencode "To=<INSERT YOUR PHONE NUMBER E.164 FORMAT>" \
-u <INSERT YOUR SUBACCOUNT SID>:<INSERT YOUR SUBACCOUNT AUTH TOKEN>

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": "+12083186206",
   "from": null,
   "messaging_service_sid": "MGxxx",
   "body": "Hi there",
   "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"
   }
}

Se a ação for bem-sucedida, você deverá receber uma mensagem de texto como esta:

Demonstração de texto de uma subconta

Ótimo, deu certo!

Conclusão: as subcontas são poderosas

Vamos recapitular tudo o que você fez:

  1. Criou uma subconta
  2. Transferiu um número de telefone da sua conta principal para a subconta
  3. Criou um serviço de mensagens na sua subconta
  4. Adicionou seu número de telefone Twilio a um serviço de mensagens
  5. Enviou uma mensagem pelo serviço de mensagens em sua subconta

Esperamos que você descubra o poder das subcontas! Este artigo só apresentou o básico. Se você gostou, talvez se interesse pelo seguinte:

Josh é engenheiro sênior de soluções da Twilio, com foco em ajudar nossos parceiros ISV (Independent Software Vendor, fornecedor independente de software) a construir arquiteturas e negócios escaláveis na Twilio. Você pode entrar em contato com ele pelo e-mail jsiverson [arroba] twilio.com.

Publicações relacionadas

Recursos relacionados

A newspaper article

Twilio Docs

De APIs a SDKs e aplicativos de amostra

Documentação de referência de API, SDKs, bibliotecas auxiliares, guias de início rápido e tutoriais para sua linguagem e plataforma.
An Open book

Centro de Recursos

Os mais recentes e-books, relatórios do setor e webinars

Aprenda com especialistas em engajamento do cliente para melhorar sua própria comunicação.
User group reactions

Ahoy

Centro da comunidade de desenvolvedores da Twilio

Melhores práticas, exemplos de código e inspiração para criar comunicações e experiências de engajamento digital.