Kuenta Docs

Appearance

Manual del Servicio de Voz de Kuenta ​

Este documento explica cómo utilizar el servicio de voz en Kuenta, incluyendo su estructura de datos, variables disponibles y consideraciones para crear plantillas efectivas.

Descripción General ​

El servicio de voz de Kuenta permite realizar comunicaciones telefónicas automatizadas mediante texto a voz. Se utiliza principalmente para verificación de identidad, notificaciones importantes y recordatorios relacionados con documentos que requieren firma.

Estructura de Datos ​

VoiceRequest ​

go
type VoiceRequest struct {
    Phone       string    // Número de teléfono al que se realizará la llamada
    CallbackURL string    // URL de callback para respuestas
    Reason      string    // Motivo de la llamada
}

VoiceTemplateVars ​

go
type VoiceTemplateVars struct {
    Sender    *Entity     // Información del remitente
    Recipient *Entity     // Información del destinatario
    Title     string      // Título del documento o mensaje
    Body      string      // Cuerpo del mensaje
    Code      string      // Código de verificación o PIN
    URL       string      // URL relevante
    SubmitURL string      // URL para enviar respuestas
}

Variables Disponibles en Plantillas ​

Las plantillas de voz tienen acceso a las siguientes variables:

.Sender     - Información del remitente
.Recipient  - Información del destinatario
.Title      - El título del documento o mensaje
.Body       - El cuerpo del mensaje
.Code       - Código de verificación o PIN
.URL        - URL relevante
.SubmitURL  - URL para enviar respuestas

Datos del Remitente y Destinatario ​

Tanto Sender como Recipient son objetos de tipo Entity con la siguiente estructura:

.ID             - ID de la entidad
.Phone          - Número de teléfono
.Email          - Correo electrónico
.Nickname       - Apodo o alias
.Verified       - Si está verificado
.Type           - Tipo de entidad (natural o legal)
.IDType         - Tipo de identificación
.IDNumber       - Número de identificación
.Profile        - Perfil con datos personales
.ImportID       - ID de importación

Datos de Perfil ​

Tanto Sender.Profile como Recipient.Profile pueden ser de tipo Natural o Legal, con la siguiente estructura:

Perfil de Tipo Natural (Persona Física) ​

.Profile.Natural.FirstName       - Nombre de la persona
.Profile.Natural.LastName        - Apellido de la persona
.Profile.Natural.IDNumber        - Número de identificación
.Profile.Natural.IDType          - Tipo de identificación
.Profile.Natural.Phone           - Teléfono personal
.Profile.Natural.Mobile          - Teléfono móvil
.Profile.Natural.Email           - Correo electrónico
.Profile.Legal.Name              - Nombre de la empresa/entidad
.Profile.Legal.LegalName         - Razón social completa
.Profile.Legal.IDNumber          - Número de identificación tributaria
.Profile.Legal.IDType            - Tipo de identificación
.Profile.Legal.Phone             - Teléfono principal
.Profile.Legal.Email             - Correo electrónico principal

Funciones de Plantillas ​

Según el análisis del código fuente en voice_service.go, el servicio de voz utiliza un modelo de plantillas simple:

go
func (vs *voiceService) Prepare(text string, vars *VoiceTemplateVars) ([]byte, error) {
    t, err := template.New("voice").Parse(text)
    if err != nil {
        return nil, err
    }
    var buffer bytes.Buffer
    err = t.Execute(&buffer, vars)
    if err != nil {
        return nil, err
    }
    return buffer.Bytes(), nil
}

A diferencia de otros servicios como documentos o webhooks, el servicio de voz no importa directamente la biblioteca Sprig ni funciones personalizadas adicionales. Solo utiliza las funciones básicas de Go Templates.

Funciones Disponibles ​

Las funciones disponibles son limitadas a las básicas de Go Templates:

{{ if }}...{{ else }}...{{ end }}   - Condiciones
{{ range .Items }}...{{ end }}      - Ciclos
{{ with .Object }}...{{ end }}      - Establecer contexto
{{ .Field }}                        - Acceso a campo

Acceso a Datos de Perfil ​

Al igual que en otros servicios, puede utilizar la función commonData para acceder a campos comunes entre perfiles:

{{ commonData .Sender.Profile "Name" }}        - Nombre (persona completo o empresa)
{{ commonData .Recipient.Profile "Name" }}     - Nombre del destinatario
{{ commonData .Sender.Profile "Email" }}       - Correo electrónico
{{ commonData .Sender.Profile "IDNumber" }}    - Número de identificación

Ejemplos de Uso de Plantillas ​

Ejemplo de Verificación con Código ​

Hola, {{ commonData .Recipient.Profile "Name" }}.
Le llamamos de {{ commonData .Sender.Profile "Name" }}.
Su código de verificación para el documento {{ .Title }} es: {{ .Code }}.
Repito, su código es: {{ .Code }}.
Por favor, ingrese este código en el sitio web para continuar con el proceso de firma.
Gracias por su atención.

Ejemplo de Notificación de Documento Pendiente ​

Hola, {{ commonData .Recipient.Profile "Name" }}.
Le informamos que tiene un documento pendiente de firma de parte de {{ commonData .Sender.Profile "Name" }}.
El documento se titula: {{ .Title }}.
Por favor, revise su correo electrónico para acceder al documento y completar el proceso de firma.
Gracias por su atención.

Ejemplo de Recordatorio de Firma Pendiente ​

Hola, {{ commonData .Recipient.Profile "Name" }}.
Le recordamos que el documento {{ .Title }} sigue pendiente de firma.
Este documento fue enviado por {{ commonData .Sender.Profile "Name" }} y requiere su atención.
Por favor, complete el proceso de firma lo antes posible.
Si necesita ayuda, comuníquese con nosotros al teléfono de soporte.
Gracias por su atención.

Mejores Prácticas ​

  1. Brevedad: Las frases deben ser cortas y concisas para una mejor comprensión auditiva

    "Le llamamos para verificar su identidad" en lugar de "El motivo de nuestra llamada es para proceder con la verificación de su identidad personal"

  2. Claridad: Evitar lenguaje complejo o técnico

    "Por favor digite el código" en lugar de "Proceda a introducir la secuencia alfanumérica"

  3. Pausas: Usar comas y puntos para controlar el ritmo del discurso

    "Su código es, 1, 2, 3, 4, 5, 6. Repito, 1, 2, 3, 4, 5, 6."

  4. Números Separados: Para que los números se pronuncien dígito por dígito, separarlos con espacios

    "Su código es: 1 2 3 4 5 6" en lugar de "Su código es: 123456"

  5. Repetición: Repetir la información importante para asegurar que el receptor la entienda

    "Su código es 1 2 3 4. Repito, su código es 1 2 3 4."

Guía Extendida para Plantillas de Voz Efectivas ​

Estructura Óptima para Mensajes de Voz ​

  1. Introducción: Presentar al llamante y propósito

    "Hola, le llamamos de [Organización]. Esta es una llamada automática..."

  2. Contexto: Explicar por qué se está realizando la llamada

    "Le contactamos en relación al documento [Título] que requiere su firma..."

  3. Acción principal: Explicar claramente qué debe hacer el destinatario

    "Para verificar su identidad, por favor ingrese el siguiente código..."

  4. Información clave: Proporcionar los datos necesarios con repetición

    "Su código es 5 8 7 2. Repito, 5 8 7 2."

  5. Instrucciones adicionales: Indicar pasos a seguir

    "Después de ingresar el código, podrá acceder al documento para firmarlo."

  6. Cierre: Agradecer y finalizar

    "Gracias por su atención. Si necesita ayuda, comuníquese con nuestro servicio al cliente."

Aspectos Técnicos del Texto a Voz ​

  1. Pronunciación de números:

    • Para códigos: Separar dígitos con espacios: "1 2 3 4"
    • Para cantidades: Escribir en formato normal: "1250" (se leerá "mil doscientos cincuenta")
    • Para fechas: Usar formato "día de mes de año": "15 de enero de 2023"

  2. Abreviaturas y siglas:

    • Evitar abreviaturas: No usar "Dr.", "Sr.", etc. Escribir completo: "Doctor", "Señor"
    • Siglas: Si se deben pronunciar letra por letra, separar con espacios: "C I F" en lugar de "CIF"

  3. Signos de puntuación:

    • Usar comas para pausas cortas
    • Usar puntos para pausas más largas
    • Usar dos puntos antes de información importante para crear énfasis

  4. Palabras problemáticas:

    • Evitar palabras con posible pronunciación ambigua
    • Sustituir palabras técnicas por términos más comunes
    • Para palabras extranjeras, usar alternativas locales cuando sea posible

Adaptación a Diferentes Contextos ​

Para Verificación de Identidad ​

Hola, le llamamos de {{ commonData .Sender.Profile "Name" }}.

Esta es una llamada para verificar su identidad.

Le enviaremos un código que deberá ingresar en la página web para confirmar que es usted.

Su código de verificación es: {{ range $i, $c := .Code }}{{ $c }} {{ end }}

Repito, su código es: {{ range $i, $c := .Code }}{{ $c }} {{ end }}

Esta verificación es necesaria para proteger la seguridad de sus datos.

Gracias por su colaboración.

Para Recordatorio de Firma Urgente ​

Hola, {{ commonData .Recipient.Profile "Name" }}.

Esta es una llamada importante de {{ commonData .Sender.Profile "Name" }}.

Le recordamos que el documento "{{ .Title }}" requiere su firma urgente.

El plazo para firmar vence hoy.

Por favor, revise su correo electrónico y complete el proceso de firma lo antes posible.

Si necesita ayuda, puede contactarnos al número que aparece en el correo electrónico.

Gracias por su atención a este asunto urgente.

Para Confirmación de Procesamiento ​

Hola, {{ commonData .Recipient.Profile "Name" }}.

Le informamos que su documento "{{ .Title }}" ha sido procesado correctamente.

Su número de confirmación es: {{ range $i, $c := .Code }}{{ $c }} {{ end }}

Por favor guarde este número para futuras referencias.

Puede acceder a su documento en cualquier momento a través de nuestra plataforma.

Gracias por utilizar nuestros servicios.

Consideraciones Psicológicas y Culturales ​

  1. Tono: Utilizar un tono formal pero amigable, evitando ser demasiado autoritario o casual

  2. Hora del día: Mencionar "buenos días", "buenas tardes" o "buenas noches" según la hora programada de la llamada

  3. Empatía: Reconocer que las llamadas automatizadas pueden no ser ideales

    "Entendemos que su tiempo es valioso, por lo que este mensaje será breve..."

  4. Opcionalidad: Indicar alternativas cuando sea posible

    "Si prefiere completar este proceso más tarde, puede hacerlo a través de nuestro sitio web..."

  5. Respeto cultural: Adaptar el nivel de formalidad según el contexto cultural

Solución de Problemas Comunes ​

Errores Comunes ​

  1. Pronunciación Incorrecta de Números:

    • Incorrecto: "Su código es 123456" (se pronunciará como "ciento veintitrés mil cuatrocientos cincuenta y seis")
    • Correcto: "Su código es 1 2 3 4 5 6" (se pronunciará dígito por dígito)

  2. Pronunciación de Caracteres Especiales:

    • Para mejorar la pronunciación de correos electrónicos:
      "Su correo es: ejemplo... arroba... dominio... punto... com"

  3. Mensajes Demasiado Largos:

    • Los mensajes muy largos pueden confundir al receptor
    • Mantener los mensajes por debajo de 30 segundos para mayor efectividad

  4. Falta de Contexto:

    • Siempre comenzar identificando quién llama y el propósito de la llamada
    • Incluir suficiente contexto para que el receptor entienda la acción requerida

Depuración ​

Para probar plantillas de voz:

  1. Leer la plantilla en voz alta para verificar claridad y longitud
  2. Verificar que los nombres y términos técnicos sean fáciles de pronunciar
  3. Asegurarse de que los códigos y números estén formateados para pronunciación correcta
  4. Probar en un entorno controlado antes de implementar en producción