> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Personalizar com propriedades

> Personalize mensagens do OneSignal usando propriedades predefinidas e tags de dados personalizadas. Acesse dados de usuário, subscription, journey, mensagem, template e app com sintaxe Liquid em e-mail, push, SMS e webhooks.

Use propriedades (como tags de usuário e identificadores como External ID) para personalizar mensagens e payloads de entrega com [sintaxe Liquid](./using-liquid-syntax).

O OneSignal renderiza os placeholders Liquid **no momento do envio**, usando dados já armazenados no usuário, subscription, Journey, mensagem, template, app ou organização. Você pode usar esses dados para personalizar mensagens, [webhooks de Journey](./journeys-webhook) e [Event Streams](./event-streams).

***

## Quando usar personalização com propriedades

Use a personalização com propriedades para renderizar conteúdo no momento do envio usando dados que já existem no OneSignal — mais comumente tags de usuário, External ID e campos de subscription como e-mail ou número de telefone.

Esta é a abordagem correta quando:

* Os dados já estão armazenados no OneSignal
* Você quer que os placeholders Liquid sejam substituídos automaticamente quando a mensagem for enviada
* Você não precisa buscar ou calcular dados frescos no momento da entrega

<Note>
  Se o valor precisa ser buscado ou calculado no momento do envio (por exemplo, preços ou estoque em tempo real), use [Data Feeds](./data-feeds) ou nossa [API com `custom_data`](./personalization-api-custom-data).

  Se o valor vem do evento que fez o usuário entrar ou progredir em um Journey, use a [personalização com Custom Events](./personalization-custom-event).
</Note>

### Suporte de canal

Cada canal suporta tipos e campos de propriedade específicos.

<Tabs>
  <Tab title="E-mail">
    Suporta [Propriedades de User e Subscription](#user-&-subscription-properties) em:

    * Assunto, Responder para e Pré-header
    * Corpo da mensagem
    * Atributos HTML (por exemplo: `<img src="{{ image_url }}" />`)
    * Ações de botão (URLs, mailto, etc.)
  </Tab>

  <Tab title="Push">
    Suporta [Propriedades de User e Subscription](#user-&-subscription-properties) em:

    * Título (`headings`), Subtítulo, Corpo (`contents`)
    * URL da imagem
    * URL de abertura: `https://example.com/{{last_category_viewed}}`

    <Warning>
      O campo `data` (dados adicionais) não suporta sintaxe Liquid.
    </Warning>
  </Tab>

  <Tab title="SMS">
    Suporta [Propriedades de User e Subscription](#user-&-subscription-properties) em:

    * Corpo da mensagem (`contents`)
  </Tab>

  <Tab title="Mensagens in-app">
    Suportam apenas substituição de tags. Propriedades, Custom Events e outras fontes de dados não estão disponíveis neste momento.

    * As tags devem ser definidas antes que o usuário inicie uma nova sessão do app.
    * A substituição de tags pode não aparecer ao usar fluxos de envio de teste.

    **Editor de blocos:** Blocos de Texto, Botão e Imagem
    **Editor HTML:** Elementos de texto e atributos (`src`, `href`, `action`, `data`)
  </Tab>

  <Tab title="Live Activities">
    Suporta [Propriedades de User e Subscription](#user-&-subscription-properties) em:

    * `event_updates`
    * `contents`
    * `headings`
  </Tab>
</Tabs>

***

## Como funciona a personalização com propriedades

O OneSignal substitui os placeholders Liquid pelos valores de propriedade correspondentes do usuário e subscription que estão recebendo a mensagem.

```liquid Liquid theme={null}
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
```

Se um usuário tiver as tags `first_name: Jon` e `level: 5`, ele verá:

```liquid Text theme={null}
Hi Jon!
Congrats on reaching level 5!
```

## Se um usuário não tiver tags definidas, ele verá os valores padrão.

## Referência de objetos Liquid de propriedades

Use esta seção para consultar os nomes exatos de objetos e campos disponíveis em Liquid.

### Propriedades de User e Subscription

Use `user` para dados no nível do usuário. Use `subscription` quando precisar de valores específicos do canal, como endereço de e-mail ou número de telefone.

<ParamField body="user.tags">
  As [Tags](./add-user-data-tags) do usuário. Você pode referenciar as tags de várias formas:

  * Use a `key` diretamente ou coloque a chave após `tags`
  * Exemplo de tags definidas: `first_name: Jon, level: 5`

  ```liquid Liquid theme={null}
  Your first name is {{ first_name }}.
  Your first name is {{ user.tags.first_name }}.
  Your level is {{ level }}.
  Your level is {{ user.tags.level }}.
  ```

  * Itere sobre as tags com sintaxe de for-loop. Este exemplo exibe pares chave:valor separados por vírgulas.

  ```liquid Liquid theme={null}
  {% for tag in user.tags %}
  {{ tag[0] }}: {{ tag[1] }}
  {% unless forloop.last %},
  {% endunless %}{% endfor %}
  ```
</ParamField>

<ParamField body="user.external_id">
  O [External ID](./users#external-id) do usuário.

  ```liquid Liquid theme={null}
  Your user ID is {{ user.external_id }}.
  Your user ID is {{ subscription.external_id }}.
  ```
</ParamField>

<ParamField body="user.onesignal_id">
  O [OneSignal ID](./users) do usuário.

  ```liquid Liquid theme={null}
  Your OneSignal user ID is {{ user.onesignal_id }}.
  ```
</ParamField>

<ParamField body="subscription.email">
  O endereço de e-mail da Subscription de e-mail que está recebendo a mensagem.

  ```liquid Liquid theme={null}
  Thanks for subscribing with email {{ subscription.email }}.
  ```
</ParamField>

<ParamField body="subscription.phone_number">
  O número de telefone da Subscription de SMS que está recebendo a mensagem.

  ```liquid Liquid theme={null}
  Thanks for subscribing with phone number {{ subscription.phone_number }}.
  ```
</ParamField>

<ParamField body="user.language">
  O código de idioma do usuário.

  ```liquid Liquid theme={null}
  Preferred language: {{ user.language }}
  Preferred language: {{ subscription.language }}
  ```
</ParamField>

<ParamField body="user.subscriptions">
  As [Subscriptions](./subscriptions) do usuário.

  * Itere sobre as subscriptions com sintaxe de for-loop.
  * Este exemplo exibe o token e o ID de cada subscription separados por vírgulas.

  ```json JSON theme={null}
  {
    "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
  }
  ```
</ParamField>

<ParamField body="subscription.unsubscribe_token">
  O token usado com a [API de cancelar inscrição de e-mail com token](/reference/unsubscribe-with-token).

  ```liquid theme={null}
  Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}
  ```
</ParamField>

### Propriedades de Journey

O objeto `journey` permite que você referencie o nome do Journey ou acesse a [personalização com Custom Events](./personalization-custom-event) para o Journey.

<ParamField body="journey.name">
  O nome do Journey.

  ```json JSON theme={null}
  {
    "journey_name": "{{ journey.name }}"
  }
  ```
</ParamField>

### Propriedades de Message

O objeto `message` fornece acesso ao ID da mensagem, nome e ID do template, o que pode ser útil para [Event Streams](./event-streams), além de acesso ao [custom\_data](./personalization-api-custom-data) para personalizar mensagens enviadas pelo seu backend.

<ParamField body="message.id">
  O ID da mensagem definido pelo OneSignal.

  ```json theme={null}
  {
    "message_id": "{{ message.id }}"
  }
  ```
</ParamField>

<ParamField body="message.name">
  O nome da mensagem definido por você, o remetente.

  ```json theme={null}
  {
    "message_name": "{{ message.name }}"
  }
  ```
</ParamField>

<ParamField body="message.template_id">
  O ID do template definido pelo OneSignal.

  ```json theme={null}
  {
    "template_id": "{{ message.template_id }}"
  }
  ```
</ParamField>

### Propriedades de Template

O objeto `template` fornece acesso ao ID e nome do [Template](./templates) usado para enviar a mensagem. Isso pode ser útil para [Event Streams](./event-streams).

<ParamField body="template.id">
  O ID do template definido pelo OneSignal.

  ```json theme={null}
  {
    "template_id": "{{ template.id }}"
  }
  ```
</ParamField>

<ParamField body="template.name">
  O nome do template definido por você, o remetente.

  ```json theme={null}
  {
    "template_name": "{{ template.name }}"
  }
  ```
</ParamField>

***

### Propriedades de App e organização

Os objetos `app` e `org` fornecem detalhes sobre o [App e Organização](./apps-organizations) que enviou a mensagem. Isso pode ser útil para [Event Streams](./event-streams).

<ParamField body="app.id">
  O ID do app definido pelo OneSignal.

  ```json theme={null}
  {
    "app_id": "{{ app.id }}"
  }
  ```
</ParamField>

<ParamField body="app.name">
  O nome do app definido por você, o proprietário do app.

  ```json theme={null}
  {
    "app_name": "{{ app.name }}"
  }
  ```
</ParamField>

<ParamField body="org.id">
  O ID da Organização definido pelo OneSignal.

  ```json theme={null}
  {
    "org_id": "{{ org.id }}"
  }
  ```
</ParamField>

<ParamField body="org.name">
  O nome da Organização definido por você, o proprietário da Organização.

  ```json theme={null}
  {
    "org_name": "{{ org.name }}"
  }
  ```
</ParamField>

***

## Exemplo: Carrinho abandonado com tags

Este exemplo mostra como personalizar mensagens de carrinho abandonado usando tags de usuário. Ele se baseia no [tutorial de Carrinho Abandonado](./abandoned-cart).

**Exemplo de tags definidas:**

```json JSON theme={null}
{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}
```

### Template de e-mail

<Steps>
  <Step title="Criar um novo template de e-mail">
    Navegue até **Mensagens > Templates > Novo Template de E-mail** e abra o Editor Arrastar e Soltar.
  </Step>

  <Step title="Adicionar a estrutura de layout">
    Crie cinco linhas:

    * Linhas 1, 2 e 4: uma coluna com um bloco de **Parágrafo**
    * Linha 3: quatro colunas com **HTML | Parágrafo | Parágrafo | Parágrafo**
    * Linha 5: uma coluna com um bloco de **Botão**

    <Frame caption="Template inicial de e-mail para carrinho abandonado">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/starter-template-abandoned-cart.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=551e9ec4618f64fdc0b6ab610a537c48" width="2968" height="2124" data-path="images/email/starter-template-abandoned-cart.png" />
    </Frame>
  </Step>

  <Step title="Adicionar liquid aos blocos de parágrafo">
    Na linha 1, adicione:

    ```liquid Liquid theme={null}
    We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!
    ```

    Na linha 2, adicione uma descrição do que o usuário está vendo:

    ```liquid Text theme={null}
    Currently in your cart:
    ```

    Na linha 4, adicione outro CTA:

    ```liquid Text theme={null}
    Checkout now while supplies last!
    ```
  </Step>

  <Step title="Exibir o item mais recente">
    Na linha 3, configure as quatro colunas:

    **Coluna 1 (bloco HTML):**

    ```html HTML theme={null}
    <img src="{{product_image}}" alt="Image" style="max-width:100%;" />
    ```

    **Colunas 2–4 (blocos de Texto):**

    * Coluna 2: `{{product_name}}`
    * Coluna 3: `{{product_quantity}}`
    * Coluna 4: `{{product_price}}`
  </Step>

  <Step title="Adicionar a URL do carrinho ao botão">
    No bloco de **Botão** da linha 5, defina a URL de ação para:

    ```liquid theme={null}
    {{cart_url}}
    ```

    <Frame caption="Template base finalizado de e-mail para carrinho abandonado sem estilização">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/finished-template-abandoned-cart-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=a46cb86b4725c27c360b9f7cd96ab305" width="2968" height="2124" data-path="images/email/finished-template-abandoned-cart-tags.png" />
    </Frame>
  </Step>

  <Step title="Testar e visualizar o template">
    Envie um e-mail de teste para você mesmo usando o botão **Testar e visualizar**.

    * Certifique-se de que as tags estejam definidas na sua Subscription de e-mail.

    <Frame caption="Visualização do e-mail com tags">
      <img src="https://mintcdn.com/onesignal/v-hm59YoewwF90UX/images/email/test-email-with-tags.png?fit=max&auto=format&n=v-hm59YoewwF90UX&q=85&s=307a846a3fec6676658ac4c653590110" width="2968" height="2124" data-path="images/email/test-email-with-tags.png" />
    </Frame>
  </Step>

  <Step title="Estilizar o template">
    <Check>Sucesso! Agora você pode aplicar seu próprio estilo ao template. Consulte [Criar e-mails com arrastar e soltar](./design-emails-with-drag-and-drop).</Check>
  </Step>
</Steps>

### Template de push

Notificações push têm espaço limitado, então exiba um item e mencione a contagem total.

**Campo de mensagem:**

Exiba o item e a contagem com gramática correta usando [declarações condicionais](./using-liquid-syntax#if-elsif-else).

```liquid Liquid theme={null}
{% assign item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}
```

**Campo de imagem:**

```liquid Liquid theme={null}
{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}
```

**Campo de URL de abertura:**

```liquid theme={null}
{{cart_url | default: "https://yourdomain.com/cart"}}
```

<Frame caption="Visualização da personalização do template de push com Testar e visualizar">
  <img src="https://mintcdn.com/onesignal/Up-pAJT_jbhthm6E/images/push/preview-push-template-personalization-with-test-preview.png?fit=max&auto=format&n=Up-pAJT_jbhthm6E&q=85&s=97db90a05acdf4ed30f54a76b1d63b98" width="2880" height="2036" data-path="images/push/preview-push-template-personalization-with-test-preview.png" />
</Frame>

<Check>Sucesso! Agora você pode criar mais templates e usá-los no [Journey de Carrinho Abandonado](./abandoned-cart).</Check>

***

## Exemplo: Personalizar uma mensagem in-app com tags

Este exemplo mostra uma mensagem in-app de recompensa personalizada com Tags. A mensagem in-app substitui valores de Tag em vários tipos de blocos.

Na mensagem configurada:

* **Bloco de texto** — exibe o nível concluído e a recompensa para esse nível
* **Bloco de imagem** — exibe a imagem para essa recompensa, com uma imagem padrão como fallback
* **Texto do botão 2** — exibe o valor da recompensa, com um padrão de `100`
* **Imagem de fundo** — definida a partir de um valor de Tag

<Frame caption="Editor de mensagem in-app com substituição de Tag configurada em blocos de texto, imagem e botão">
  <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b697ab5-config1.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=c40e541c296b138a7f04ac561b3b0c64" alt="" width="872" height="968" data-path="images/docs/b697ab5-config1.png" />
</Frame>

A mensagem é renderizada no início da sessão usando os valores de Tag atuais do usuário:

<Frame caption="Mensagem in-app exibida ao usuário com valores substituídos a partir de Tags">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/973f097-JustTheIAMTagSub.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=0626ef7b31dfbfece633e74b072fbff5" style={{ width:"100%" }} width="338" height="607" data-path="images/docs/973f097-JustTheIAMTagSub.png" />
</Frame>

<Note>
  Consulte a aba **Mensagens in-app** em [Suporte de canal](#suporte-de-canal) acima para conhecer os blocos, atributos e regras de tempo suportados. Dois lembretes que vale a pena reforçar dali:

  * **As Tags devem ser definidas antes do usuário iniciar uma nova sessão do app.** Tags atualizadas no meio da sessão não são renderizadas em mensagens in-app exibidas nessa sessão.
  * **A substituição de Tags não é renderizada nos envios de "Enviar Mensagem de Teste".** Acione a mensagem a partir de uma sessão real para verificar a substituição.
  * [A substituição de propriedades](./using-liquid-syntax#property-include) não é suportada em mensagens in-app.
</Note>

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Personalização de mensagens" href="./message-personalization" icon="sparkles">
    Visão geral de todas as opções de personalização no OneSignal, incluindo quando usar Custom Events vs outros métodos.
  </Card>

  <Card title="Tags" href="./add-user-data-tags" icon="tag">
    Saiba como definir tags em usuários via SDK, API ou importação CSV.
  </Card>

  <Card title="Usando sintaxe Liquid" href="./using-liquid-syntax" icon="droplet">
    Referência completa de Liquid com filtros, condicionais, loops e manipulação de strings.
  </Card>

  <Card title="Templates" href="./templates" icon="file">
    Crie e gerencie templates de mensagens reutilizáveis para uso em Journeys.
  </Card>

  <Card title="Tutorial de carrinho abandonado" href="./abandoned-cart" icon="cart-shopping">
    Construa um Journey de carrinho abandonado usando Tags e Propriedades.
  </Card>
</Columns>

<Info>
  Precisa de ajuda?

  Converse com nossa equipe de Suporte ou envie email para `support@onesignal.com`

  Por favor inclua:

  * Detalhes do problema que você está enfrentando e passos para reproduzir se disponível
  * Seu OneSignal App ID
  * O External ID ou Subscription ID se aplicável
  * A URL para a mensagem que você testou no Dashboard OneSignal se aplicável
  * Quaisquer [logs ou mensagens de erro](/docs/pt-BR/capturing-a-debug-log) relevantes

  Estamos felizes em ajudar!
</Info>

***