Casos de uso da API

A REST API da Braze fornece uma ampla gama de endpoints projetados para ajudar a gerenciar e otimizar sua estratégia de engajamento do cliente. Neste artigo, exploraremos vários casos de uso para cada coleção de endpoints: catálogos, listas e endereços de e-mail, exportação, mensagens, Central de Preferências, SMS, grupos de inscrições, modelos e dados de usuários.

Cada seção apresenta um cenário com um guia passo a passo, exemplo de código e resultado esperado. Ao final deste artigo, você entenderá melhor como usar a REST API da Braze para aprimorar seus esforços de engajamento do cliente.

Excluindo múltiplos itens de um catálogo

Um novo ano traz novos lançamentos de produtos na Kitchenerie, uma marca de varejo especializada em utensílios de cozinha. No dashboard da Braze, a Kitchenerie tem um catálogo configurado para sua coleção de louças chamado “Dishware”. Este novo ano também significa remover os seguintes produtos de sua coleção de louças.

• Plain Bisque
• Pearl Porcelain
• Pink Shimmer

Para remover esses produtos de seu catálogo, a Kitchenerie pode usar o endpoint /catalogs/{catalog_name}/items para enviar os IDs dos itens.

Veja o exemplo de solicitação:

1
2
3
4
5
6
7
8
9
10

curl --location --request DELETE 'https://rest.iad-03.braze.com/catalogs/dishware/items' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-REST-API-KEY' \
--data-raw '{
  "items": [
    {"id": "plainbisque"},
    {"id": "pearlporcelain"},
    {"id": "pinkshimmer"}
  ]
}'

Após enviar essa carga útil, a resposta confirma que a Braze removeu com sucesso as três coleções do catálogo de louças da Kitchenerie.

1
2
3

{
  "message": "success"
}

Removendo e-mails da lista de spam da Braze

Na MovieCanon, uma empresa de serviços de streaming, a equipe de desenvolvedores é responsável por auditar periodicamente suas listas de e-mails para identificar e manter os usuários inscritos em suas campanhas de e-mail. Como parte dessa auditoria, a MovieCanon deseja remover esta lista de e-mails da sua lista de spam:

• august.author.example.com
• [email protected]
• [email protected]
• [email protected]
• [email protected]

Para realizar essa tarefa, a equipe de desenvolvedores precisa de uma chave de API com a permissão email.spam.remove para usar o endpoint /email/spam/remove. Esse endpoint remove endereços de e-mail da lista de spam da Braze e da lista de spam mantida pelo provedor de e-mail da MovieCanon.

Para enviar essa solicitação, inclua um endereço de e-mail como string ou um array de até 50 endereços de e-mail a serem modificados. Como a lista de e-mails a remover tem menos de 50, a MovieCanon pode realizar essa tarefa com o seguinte corpo de solicitação:

1
2

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY

1
2
3

{
  "email": ["august.author.example.com","[email protected]","[email protected]","[email protected]","[email protected]"]
}

Após enviar esse payload com sucesso, esta resposta confirma que a Braze removeu os e-mails da lista de spam da MovieCanon.

1
2
3

{
  "message": "success"
}

Auditoria de todos os Canvas

A Siege Valley Health é um sistema hospitalar que inclui 10 hospitais e centros de pesquisa em operação, com milhares de pacientes. Sua equipe de marketing quer comparar os Canvas enviados aos pacientes para lembrá-los de agendar uma consulta para vacinas contra a gripe nos últimos 3 anos de uso da Braze. A equipe de marketing da Siege Valley Health também quer uma maneira rápida e eficiente de visualizar tanto a lista de Canvas quanto o resumo de análise de dados.

O exemplo a seguir mostra como a Siege Valley Health pode realizar essas duas tarefas usando uma combinação de endpoints, em vez de filtrar pelo dashboard da Braze.

Para a primeira tarefa de auditoria dos Canvas, use o endpoint /canvas/list para exportar uma lista de Canvas que inclui o nome e as tags. Veja um exemplo de solicitação:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "canvases" : [
  	{
  		"id": "canvas_identifier_1",
  		"last_edited": "2020-07-10T23:59:59",
  		"name": "PatientReminder_FluShot_2020",
  		"tags": {
        "flu_shots", "patienthealth", "2020"
      }
  	},
  	{
  		"id": "canvas_identifier_2",
  		"last_edited": "2020-07-30T23:59:59",
  		"name": "PatientReminder2_FluShot_2020",
  		"tags": {
        "flu_shots", "patienthealth", "reminder", "2020"
      }
  	},
    ... (more Canvases)
  ],
  "message": 'success'
}

Vamos passar para a próxima tarefa de visualizar o resumo de análise de dados do primeiro Canvas da lista de Canvas da Siege Valley Health. Para isso, usaríamos o endpoint /canvas/data_summary com os seguintes parâmetros de solicitação:

• canvas_id: “canvas_identifier_2”
• ending_at: 2023-07-10T23:59:59
• starting_at: 2020-07-10T23:59:59

Veja um exemplo de solicitação:

1
2

curl --location -g --request GET 'https://rest.iad-01.braze.com/canvas/data_summary?canvas_id=&ending_at=2023-07-10T23:59:59&starting_at=2020-07-10T23:59:59&length=5&include_variant_breakdown=false&include_step_breakdown=false&include_deleted_step_data=false' \
--header 'Authorization: Bearer YOUR-REST-API-KEY'

Verificando campanhas e Canvas agendados para as próximas datas

A época mais movimentada do ano está se aproximando rapidamente para a Flash & Thread, uma marca de varejo que vende roupas e produtos de beleza online e em lojas físicas. Sua equipe de marketing quer verificar as campanhas e Canvas programados a partir do dashboard da Braze antes de 31 de março de 2024, às 12h. Isso pode ser feito usando o endpoint /messages/scheduled_broadcasts.

Aqui está um exemplo de requisição:

1
2

curl --location --request GET 'https://rest.iad-01.braze.com/messages/scheduled_broadcasts?end_time=2024-03-31T12:00:00' \
--header 'Authorization: Bearer YOUR-REST-API-KEY'

Esse endpoint retorna a lista de campanhas e Canvas programados. A partir daí, a equipe de marketing pode confirmar sua lista de mensagens consultando o campo name das campanhas e Canvas na resposta.

Visualizando uma Central de Preferências mais antiga

A PoliterWeekly é uma revista digital cujos assinantes podem ser alcançados por e-mail. Em um esforço para entender melhor a jornada de seus assinantes, a equipe de marketing quer revisar os detalhes da Central de Preferências da PoliterWeekly para verificar quando ela foi criada e atualizada pela última vez.

Usando o endpoint /preference_center/v1/{preferenceCenterExternalID}, a equipe de marketing precisa apenas inserir o ID externo da Central de Preferências como parâmetro de caminho, ficando assim:

1
2

curl --location -g --request GET https://rest.iad-01.braze.com/preference_center/v1/politer_weekly_preference_center_api_id \
--header 'Authorization: Bearer YOUR-REST-API-KEY'

1
2
3
4
5
6
7
8
9
10
11
12
13
14

{
  "name": "PoliterWeekly Notification Preferences",
  "preference_center_api_id": "user_engage_pref_123",
  "created_at": "2021-04-03T12:00:00",
  "updated_at": "2024-08-15T15:00:00",
  "preference_center_title": "Manage Your PoliterWeekly Notification Preferences",
  "preference_center_page_html": "<!DOCTYPE html><html><head><title>Your PoliterWeekly Newsletter Preferences</title><style>body { font-family: Arial, sans-serif; margin: 0; padding: 20px; }.container { max-width: 600px; margin: auto; }h1 { color: #333; }.preference { margin-bottom: 20px; }.preference label { font-size: 16px; }.preference input[type=\"checkbox\"] { margin-right: 10px; }.submit-btn { background-color: #007bff; color: white; padding: 10px 20px; border: none; cursor: pointer; }</style></head><body><div class=\"container\"><h1>Manage your notification preferences</h1><p>Select the types of updates you wish to receive from us:</p><form id=\"preferencesForm\"><div class=\"preference\"><label><input type=\"checkbox\" name=\"newsUpdates\" checked> News Updates</label></div><div class=\"preference\"><label><input type=\"checkbox\" name=\"editorialPicks\"> Editorial Picks</label></div><div class=\"preference\"><label><input type=\"checkbox\" name=\"events\"> Events & Webinars</label></div><div class=\"preference\"><label><input type=\"checkbox\" name=\"specialOffers\"> Special Offers & Promotions</label></div><button type=\"submit\" class=\"submit-btn\">Save Preferences</button></form></div><script>document.getElementById('preferencesForm').addEventListener('submit', function(e) {e.preventDefault();alert('Your preferences have been saved!');});</script></body></html>",
  "confirmation_page_html": "<!DOCTYPE html><html><head><title>PoliterWeekly Preferences Updated</title></head><body><h1>You're good to go!</h1><p>Braze updated your preferences successfully.</p></body></html>",
  "redirect_page_html": null,
  "preference_center_options": {
    "meta-viewport-content": "width=device-width, initial-scale=1"
  },
  "state": "active"
}

Removendo números de telefone inválidos

Na CashBlastr, o objetivo principal é simplificar a forma como as pessoas enviam e recebem pagamentos rápidos. Como empresa de serviços financeiros, a CashBlastr quer manter sua lista de números de telefone dos clientes atualizada e precisa. A equipe de desenvolvimento foi encarregada de remover a seguinte lista de números de telefone marcados como “inválidos” para que as mensagens SMS da equipe de marketing possam alcançar os clientes apropriados da CashBlastr.

• 12223135467
• 12183095514
• 14235662245
• 14324567892

Para enviar uma solicitação com o endpoint /sms/invalid_phone_numbers/remove, os números de telefone devem estar em um array de strings no formato e.164, com até 50 números de telefone por solicitação. Como a lista não excede 50 números de telefone, veja um exemplo do corpo da solicitação que a equipe de desenvolvimento da CashBlastr enviaria:

1
2
3
4
5

Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "phone_numbers": ["12183095514","14255551212"]
}

Após enviar essa carga útil, a resposta confirma que a Braze removeu os números de telefone inválidos da CashBlastr da lista de inválidos da Braze.

1
2
3

{
  "message": "success"
}

Verificando o status do grupo de inscrições de um usuário

SandwichEmperor é uma rede de restaurantes de serviço rápido nos Estados Unidos, e sua equipe de marketing deseja verificar os status dos grupos de inscrições de uma lista aleatória de usuários para SMS. Usando o endpoint /subscription/status/get, a SandwichEmperor pode realizar essa tarefa para um usuário individual com o seguinte exemplo de solicitação:

1
2

curl --location -g --request GET 'https://rest.iad-01.braze.com/subscription/status/get?subscription_group_id={{subscription_group_id}}&phone=+11232223333' \
--header 'Authorization: Bearer YOUR-REST-API-KEY'

Esse endpoint também lista os status dos grupos de inscrições de um usuário para e-mail. Use-o para ver o status do grupo de inscrições de vários usuários.

Verificando um modelo HTML para envio de mensagens de e-mail

Na WorkFriends, uma rede social que ajuda a construir conexões entre profissionais de diferentes setores, a equipe de marketing é responsável por enviar Campaigns de e-mail para seus usuários. Essas Campaigns geralmente incluem lembretes de eventos locais, newsletters semanais e destaques de atividades de perfil.

Neste cenário, a WorkFriends historicamente utilizou um único modelo HTML com sua identidade visual antiga. Em um esforço para alinhar sua identidade de marca, a WorkFriends quer verificar se há alguma informação útil nesse modelo HTML para aproveitar antes de fazer a transição para um novo modelo.

1
2
3
4
5
6
7
8
9
10
11

{
  "email_template_id": "WorkFriends_Email_Template_ID",
  "template_name": "Promo template",
  "description": "Promo template",
  "subject": "WorkFriends Weekly Newsletter",
  "preheader": "Another week, another WorkFriends update",
  "body": "<!DOCTYPE html><html><head><title>WorkFriends Weekly Newsletter</title><style>body {font-family: Arial, sans-serif; color: #333;}.container {padding: 20px;}.header {background-color: #f2f2f2; padding: 10px; text-align: center;}.content {margin-top: 20px;}.footer {margin-top: 20px; font-size: 12px; text-align: center; color: #777;}</style></head><body><div class=\"container\"><div class=\"header\"><h2>WorkFriends Weekly Newsletter</h2></div><div class=\"content\"><p>Hello WorkFriends,</p><p>Welcome to another edition of our weekly newsletter. We've got some exciting updates and promos for you this week!</p><!-- Add more content here --><p>Don't forget to check out our latest promos and updates. Stay connected, stay informed!</p></div><div class=\"footer\"><p>Thank you for being a part of WorkFriends.</p><p>Unsubscribe | Update Preferences</p></div></div></body></html>",
  "tags": "promo",
  "created_at": "2020-07-10 13:00:00.000",
  "updated_at": "2024-02-04 17:00:00.000"
}

Após revisar as informações desse modelo, a WorkFriends também pode usar o endpoint /templates/email/update para atualizar o modelo de e-mail por meio da API. O modelo de e-mail no dashboard da Braze reflete essas edições.