Una variable es un marcador de posición en el texto de un mensaje. Cada destinatario recibe en su lugar su propio valor: un nombre, el nombre de una empresa, un número de pedido. Así envía un único texto a miles de personas y cada una de ellas lee un mensaje escrito para ella. Las variables se escriben igual en una campaña y en la API.

## Cómo escribir una variable

Una variable es un nombre entre corchetes angulares, por ejemplo `<first_name>`. Al enviar el mensaje, se sustituye por el valor que tiene para ese destinatario:

| texto del mensaje | lo que recibe el destinatario |
|:--|:--|
| `Hola <first_name>, su pedido está en camino.` | `Hola Pedro, su pedido está en camino.` |

- **El nombre tiene que coincidir exactamente.** Las mayúsculas, las minúsculas y los espacios importan: ni `<First_Name>` ni `< first_name >` se sustituyen por el valor de `first_name`.
- **Un valor vacío equivale a ninguno.** Un texto vacío o formado solo por espacios cuenta como valor que falta; lo que ocurre entonces se describe en [Cuando falta el valor](#cuando-falta-el-valor).

> [!WARNING]
> Todo lo que esté escrito como `<algo:algo>`, `<algo=número>` o `<algo|filtro>` se interpreta siempre como una variable, aunque no tenga ninguna variable con ese nombre, y cambia en el mensaje enviado. Escribirlo como `&lt;` tampoco sirve. Un `<` aislado o `<b>` se mantiene tal cual.

## Cuando falta el valor

Cuando no tiene un valor para un destinatario, la variable se queda en el mensaje **literalmente**: el destinatario recibe `Hola <first_name>, …`. Puede evitarlo con un valor predeterminado escrito después de dos puntos:

| notación | lo que recibe un destinatario sin valor |
|:--|:--|
| `<first_name>` | literalmente `<first_name>` |
| `<first_name:cliente>` | el texto alternativo `cliente` |
| `<first_name:>` | nada: la variable se omite |

Un destinatario del que sí tiene un valor recibe su propio valor en los tres casos.

> [!TIP]
> Utilice una variable sin valor predeterminado solo cuando tenga datos de todos los destinatarios. En caso contrario, añada un texto alternativo o deje que se omita.

## Filtros

Un filtro ajusta el valor que se rellena: lo convierte en mayúsculas, elimina espacios, crea una forma de tratamiento a partir de un nombre o controla su longitud. Se escribe después de una barra vertical, justo detrás del nombre de la variable: `<first_name|upper>`. Puede escribir varios filtros seguidos y se aplican de izquierda a derecha: `<city|trim|capitalize>`; encontrará más información en [Encadenamiento de filtros](#encadenamiento-de-filtros).

### Mayúsculas y minúsculas

| notación | lo que hace el filtro | ejemplo |
|:--|:--|:--|
| `<last_name\|upper>` | convierte todo el valor en mayúsculas | `Juan García` → `JUAN GARCÍA` |
| `<last_name\|lower>` | convierte todo el valor en minúsculas | `Juan García` → `juan garcía` |
| `<last_name\|first_upper>` | pone en mayúscula la primera letra y deja el resto sin cambios | `juan garcía` → `Juan garcía` |
| `<last_name\|capitalize>` | empieza cada palabra con mayúscula y pone todas las demás letras en minúscula | `jUAN gARCÍA` → `Juan García` |

### Ajustes de texto

| notación | lo que hace el filtro | ejemplo |
|:--|:--|:--|
| `<last_name\|trim>` | elimina los espacios del principio y del final | `" Juan García "` → `"Juan García"` |
| `<last_name\|ascii>` | elimina los signos diacríticos | `Šťastný` → `Stastny` |
| `<city\|webalize>` | convierte el valor en un formato para direcciones web: sin signos diacríticos, en minúsculas y con las palabras unidas por guiones | `Ústí nad Labem` → `usti-nad-labem` |
| `<company_name\|word:1>` | elige una palabra según su posición; cuando el valor no tiene tantas palabras, no se rellena nada | `Kytary Novák` → `Kytary` |
| `<company_name\|initial>` | iniciales: la primera letra de cada palabra, en mayúscula y seguida de un punto | `Kytary Novák` → `K. N.` |

### Nombre y forma de tratamiento

Dos filtros trabajan con nombres checos: `vocative` crea la forma de tratamiento en el caso vocativo checo y `gender` elige un texto para un hombre o para una mujer según el nombre. Siguen las mismas reglas que las variables `<first_name_vokativ>` y `<last_name_vokativ>`; cómo se crea el vocativo se describe en [Vocativo checo](https://www.bulkgate.com/es/centro-de-ayuda/herramientas/vocativo-checo/).

| notación | lo que hace el filtro | ejemplo |
|:--|:--|:--|
| `<first_name\|vocative>` | pone cada palabra del valor en vocativo | `Petr Novák` → `Petře Nováku` |
| `<first_name\|gender:Milý,Milá>` | rellena el primer texto para un nombre masculino y el segundo para uno femenino; el valor en sí no se rellena | `Jana` → `Milá` |

- **Vocativo a partir de cualquier variable.** A diferencia de `<first_name_vokativ>`, el filtro `vocative` puede utilizarse con cualquier variable, por ejemplo con un nombre completo guardado en un solo campo o con un valor que envíe en la API.
- **El género y el tipo de nombre** los reconoce el propio filtro `vocative` a partir de la terminación. Cuando se equivoca, los puede indicar con parámetros: el primero es `man` o `woman`, el segundo `first` (nombre de pila) o `last` (apellido), por ejemplo `<last_name|vocative:woman,last>`. El valor predeterminado de ambos parámetros, `auto`, deja la decisión al filtro.
- **Mayúsculas y minúsculas.** Cada palabra en vocativo empieza con mayúscula y las demás letras van en minúscula: `NOVÁK` → `Nováku`.
- **El valor predeterminado también se declina**, así que escríbalo en nominativo: un destinatario sin nombre recibe `Zákazníku` a partir de `<first_name:zákazník|vocative>`.
- **El texto del género sustituye al valor**, así que escriba la variable dos veces en el texto: `<first_name|gender:Milý,Milá> <first_name|vocative>` da `Milý Petře` o `Milá Jano`. El texto también puede ser solo el final de una palabra: `Vážen<first_name|gender:ý pane,á paní>` da `Vážený pane` o `Vážená paní`. Ambos textos son obligatorios, pero pueden estar vacíos; no pueden contener `<`, `>`, `|` ni comas.
- **Sin nombre**, el género se decide a partir del valor predeterminado: `<first_name:zákazníku|gender:Milý,Milá>` da `Milý` a un destinatario sin nombre. Un valor predeterminado vacío da siempre el texto para un hombre.

> [!WARNING]
> Ambos filtros siguen las reglas del checo, sin importar de dónde procede el nombre. El nombre inglés John obtiene la forma `Johne`. Utilícelos solo en mensajes para destinatarios checos y compruebe el resultado de los nombres poco habituales con un mensaje de prueba.

### Límite de longitud

Los filtros con un número controlan el número máximo de caracteres que puede tener el valor. Resultan útiles con valores largos, como el nombre de una empresa o una dirección, que de otro modo alargarían el mensaje hasta otra parte de SMS. El filtro decide qué ocurre con un valor más largo:

| notación | qué ocurre con un valor más largo | “Kytary Novák” con un límite de 8 |
|:--|:--|:--|
| `<company_name\|cut:8>` | se corta en el límite, por palabras completas siempre que sea posible | `Kytary` |
| `<company_name\|truncate:8>` | se corta y se completa con `...`, de modo que ambos quepan en el límite | `Kytar...` |
| `<company_name\|ellipsis:8>` | se sustituye por `(...)` | `(...)` |
| `<company_name\|empty:8>` | se omite | nada |
| `<company_name:su empresa\|fallback:8>` | se sustituye por el valor predeterminado de la variable; si no lo tiene, se omite | `su empresa` |

Un valor que cabe en el límite se inserta completo.

Con `truncate`, `ellipsis` y `fallback` puede escribir después de una coma su propio texto, que se utiliza en lugar del predeterminado:

| notación | “Kytary Novák” con un límite de 8 |
|:--|:--|
| `<company_name\|truncate:8,…>` | `Kytary…` |
| `<company_name\|ellipsis:8,su empresa>` | `su empresa` |
| `<company_name\|fallback:8,su empresa>` | `su empresa` |

Su propio texto no puede contener `<`, `>`, `|` ni comas. Un texto vacío (`truncate:8,`) corta el valor sin sufijo.

### Encadenamiento de filtros

Puede combinar los filtros libremente: basta con escribirlos uno tras otro, cada uno después de su propia barra vertical. Se aplican sucesivamente de izquierda a derecha y cada filtro recibe el resultado del anterior. Así puede combinar un límite de longitud con un cambio de mayúsculas y minúsculas y con la eliminación de espacios.

| notación | valor del contacto | lo que recibe el destinatario |
|:--|:--|:--|
| `<last_name\|lower\|first_upper>` | `GARCÍA` | `García` |
| `<city\|trim\|capitalize>` | `"  nueva york  "` | `Nueva York` |
| `<company_name\|trim\|truncate:8,…\|upper>` | `"  Kytary Novák "` | `KYTARY…` |
| `<first_name\|word:1\|vocative>` | `Petr Pavel` | `Petře` |

En el tercer ejemplo, `trim` elimina primero los espacios, `truncate:8,…` recorta el valor a `Kytary…` y `upper` lo convierte finalmente en mayúsculas.

- **El orden importa.** Los mismos filtros en otro orden dan un resultado distinto. Con el valor `"  Ústí nad Labem  "`, `<city|trim|cut:4>` da `Ústí`, mientras que `<city|cut:4|trim>` primero recorta el valor a los espacios iniciales y después los elimina: no queda nada.
- **El valor predeterminado va antes de los filtros**, y toda la cadena lo ajusta también: un destinatario sin nombre de pila recibe `CLIENTE` a partir de `<first_name:cliente|trim|upper>`.
- **Cada aparición de una variable tiene sus propios filtros.** Puede usar una misma variable varias veces en el texto, cada vez de forma distinta: a partir de `Hola <first_name|first_upper>, <first_name|upper>`, un destinatario con el valor `juan` recibe `Hola Juan, JUAN`.
- **En el editor de campañas**, la cadena sigue el orden de los filtros en el cuadro de diálogo de la variable, y el orden se cambia arrastrándolos. Cada filtro se puede usar allí una sola vez.

> [!TIP]
> Coloque `trim` antes de los filtros que limitan la longitud. De lo contrario, los espacios iniciales también cuentan para el límite: a partir del valor `"  Kytary Novák "`, `<company_name|cut:8>` da solo `"  Kytary"`, mientras que `<company_name|trim|cut:8>` da `Kytary`.

### Qué hay que tener en cuenta

Escriba el nombre del filtro en minúsculas y sin espacios, y el número solo con cifras.

> [!IMPORTANT]
> Ni un filtro ni un límite impiden que una variable sin valor se quede en el texto. Un destinatario del que no tiene valor recibe literalmente `<company_name>` a partir de `<company_name|cut:8>`. Si quiere un texto alternativo, escríbalo después de dos puntos, antes de los filtros: `<company_name:su empresa|cut:8>`.

> [!WARNING]
> Una errata en un filtro estropea la variable. Un filtro desconocido o un número que falta (`<first_name|bold>`, `<first_name|cut>`) hacen que la notación deje de ser una variable y se quede literalmente en el texto, incluso para los destinatarios que sí tienen nombre de pila. Cuando la variable tiene un valor predeterminado, el filtro erróneo pasa a formar parte del texto alternativo: `<first_name:cliente|Upper>` rellena el nombre de pila o `cliente|Upper`.

### Notación obsoleta con signo igual

Antes, la longitud se limitaba con un atajo: el límite se escribía después de un signo igual, seguido de una letra que determinaba qué ocurría con un valor más largo. **Esta notación está obsoleta**: utilice filtros en los mensajes nuevos. Los mensajes que la contienen siguen funcionando y el editor de campañas la reescribe como filtro.

| notación obsoleta | sustitúyala por el filtro |
|:--|:--|
| `<company_name=8>` o `<company_name=8c>` | `<company_name\|cut:8>` |
| `<company_name=8t>` | `<company_name\|truncate:8>` |
| `<company_name=8s>` | `<company_name\|ellipsis:8>` |
| `<company_name=8e>` | `<company_name\|empty:8>` |
| `<company_name:su empresa=8d>` | `<company_name:su empresa\|fallback:8>` |

El atajo se aplica como primer filtro, aunque le sigan otros: `<company_name=8|upper>` equivale a `<company_name|cut:8|upper>`.

## Variables en una campaña

Una campaña toma los valores de los contactos que le añade: de la agenda de contactos, de la importación de un archivo y de los números introducidos a mano.

1. **Añada primero los destinatarios.** El menú de variables muestra solo los campos que tiene rellenos al menos un destinatario de la campaña. Sin destinatarios está vacío.
2. En el editor de texto, haga clic en el icono `Agregar variable` o simplemente escriba `@`. Al escribir un nombre, el menú se filtra.
3. Elija la variable. Para cada una verá qué porcentaje de destinatarios tiene datos para ella.

La variable aparece en el texto como una etiqueta con el nombre del campo, y su color le indica cómo está de datos:

- **sin resaltar**: todos los destinatarios tienen los datos o hay un valor predeterminado,
- **advertencia**: del 30 al 99 % de los destinatarios tienen los datos,
- **error**: menos del 30 % de los destinatarios tienen los datos o el campo no existe.

Haga clic en la etiqueta para ver un resumen de la variable, incluidos sus filtros activos en el orden en que se aplican, y edítela desde allí:

- **Cuando falta el valor**: añada un texto alternativo, deje que la variable se omita o manténgala en el texto.
- **Filtros**: añádalos uno a uno desde un menú dividido en mayúsculas y minúsculas, ajustes de texto, nombre y forma de tratamiento, y longitud. En los filtros con parámetro, rellene un número o un texto, o elija una opción. El orden se cambia arrastrando el asa (los filtros se aplican de arriba abajo) y puede eliminar un filtro que no necesite. Un valor de ejemplo muestra lo que hace el filtro.

El editor guarda la variable con la misma notación descrita en [Cuando falta el valor](#cuando-falta-el-valor) y [Filtros](#filtros), por ejemplo `<company_name:su empresa|trim|cut:8>`. Un atajo antiguo con signo igual se reescribe de paso como filtro.

### Qué campos puede utilizar

| variable | lo que contiene |
|:--|:--|
| `<first_name>`, `<last_name>` | nombre de pila y apellido |
| `<first_name_vokativ>`, `<last_name_vokativ>` | nombre de pila y apellido en el caso vocativo checo; se rellenan automáticamente, consulte [Vocativo checo](https://www.bulkgate.com/es/centro-de-ayuda/herramientas/vocativo-checo/) |
| `<title_before>`, `<title_after>` | título antes y después del nombre |
| `<company_name>` | nombre de la empresa |
| `<company_number>`, `<company_vat>` | número de registro de la empresa y número de IVA |
| `<email>` | correo electrónico |
| `<url>` | dirección web |
| `<street1>`, `<street2>`, `<city>`, `<zip>`, `<state>`, `<country>` | dirección: calle, ciudad, código postal, estado, país |
| `<phone_mobile>` | número de teléfono |
| `<note>` | nota |
| `<custom_field_0>` a `<custom_field_9>` | campos personalizados |

Cuando [importa desde un archivo](https://www.bulkgate.com/es/centro-de-ayuda/campanas/importar-desde-csv-excel/), asigna cada columna a uno de estos campos. Una columna que no encaja en ninguno de ellos (un número de pedido, el importe de un descuento) va a un campo personalizado, y en el texto utiliza entonces, por ejemplo, `<custom_field_0>`.

### Canales, longitud y vista previa

- **Canales.** Las variables funcionan en el texto de los mensajes SMS, Viber y RCS y, en RCS, también en el título.
- **Longitud y precio.** El contador de caracteres del editor cuenta con los valores del contacto seleccionado en la vista previa. Sin embargo, cada destinatario puede tener valores de distinta longitud, por lo que el número de partes de SMS y el precio se calculan para cada destinatario por separado, después de rellenar los valores.
- **Unicode.** Los signos diacríticos de un valor rellenado cambian el SMS a Unicode solo si lo tiene activado en los ajustes del texto.
- **Vista previa.** Tanto la vista previa del mensaje como `Enviar mensaje de prueba` rellenan los valores del contacto seleccionado en la vista previa, así que ve cómo queda el texto antes de enviarlo. Los filtros `vocative` y `gender` son la excepción: la vista previa del editor no declina el nombre, solo lo marca con 🗣️, y para `gender` muestra ambos textos, por ejemplo `Milý/Milá`. El contador de caracteres también cuenta con estas formas. El resultado real lo verá en un mensaje de prueba.

## Variables en la API

En la API, los valores se envían directamente en la solicitud, en el parámetro `variables`: un objeto cuya clave es el nombre de la variable y cuyo valor es lo que se debe rellenar. El texto usa la misma notación, incluidos los valores predeterminados y los [filtros](#filtros).

```json
{
	"number": "420777777777",
	"text": "Hola <first_name:cliente>, el pedido <order> está en camino.",
	"variables": {"first_name": "Pedro", "order": "12345"}
}
```

El destinatario recibe `Hola Pedro, el pedido 12345 está en camino.` Puede llamar a la variable como quiera: `<order>` del ejemplo no es un campo del contacto, sino solo una clave de `variables`.

### Dónde se colocan las variables

| API | dónde va `variables` |
|:--|:--|
| [Advanced API – transaccional](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-transactional/2.0/) | con todo el mensaje; en la versión 2.0 también con cada número de `number` por separado; los valores junto al número tienen prioridad |
| [Advanced API – promocional](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-promotional/2.0/) | con cada número de `number` por separado; `variables` para todo el mensaje no se utiliza |
| [Advanced API – grupos de la agenda de contactos](https://www.bulkgate.com/es/documentacion/advanced-api/advanced-envio-a-grupos/) | no se envía: se rellenan los campos de los contactos de la agenda, con los mismos nombres que en una [campaña](#que-campos-puede-utilizar) |
| [Integration API](https://www.bulkgate.com/es/documentacion/integration-api/integration-transaccional/) | con cada mensaje |

### Qué valores enviar

- **Texto o un número.** Los números se rellenan tal cual (`12` → `12`).
- **`null`, `false` y el texto vacío** cuentan como valor que falta: se aplica el [valor predeterminado](#cuando-falta-el-valor); si no lo hay, la variable se queda literalmente en el texto.
- **Un array o un objeto como valor** no lo acepta la Advanced API, que devuelve el error `invalid_input_parameters`.
- **Las claves adicionales** que no están en el texto se ignoran.
- **Caso vocativo.** A partir de `first_name` y `last_name`, la Advanced API calcula por sí misma `first_name_vokativ` y `last_name_vokativ`, y sobrescribe sus propios valores de estas dos claves. La Integration API no calcula el vocativo. Cómo funciona se describe en [Vocativo checo](https://www.bulkgate.com/es/centro-de-ayuda/herramientas/vocativo-checo/).

### Canales y longitud

| canal | dónde se rellenan las variables |
|:--|:--|
| SMS | texto |
| Viber | texto, rótulo del botón y enlace |
| RCS | texto, título y descripción de la tarjeta |
| Voice | texto |

El número de partes de SMS y el precio se calculan a partir del texto después de rellenar los valores. Los signos diacríticos de un valor rellenado cambian el SMS a Unicode solo con `"unicode": true`. El texto de Viber, RCS y WhatsApp que supera el límite del canal después de rellenar los valores (Viber 1 000 caracteres, RCS y WhatsApp 5 000) se recorta.

> [!NOTE]
> Los plugins para e-shops tienen su propio conjunto de variables, por ejemplo `<customer_firstname>`. Se describen en [SMS para clientes](https://www.bulkgate.com/es/centro-de-ayuda/integraciones/modulos-de-e-commerce/sms-para-clientes/).