# Definición de Campos

> Definición de Campos del Agente de IA

Source: https://docs.plazbot.com/kb/agentes-fields

### Campos Principales.

En esta sección se verá todos los campos correspondientes al agente de IA, a nivel de configruacion. En esta sección no se verán los campos de `services`, `channels` y `actions`.

### Archivo de Configuración - agent.config.json

Información global del archivo de configuración del Agente de IA

```json
{
  "name": "Sales Clinic",
  "description": "Virtual Agent IA assistant of the Dental Clinic Smiles",
  "prompt": "You are Máximo, a professional virtual assistant for Smiles Dental Clinic. Help patients with appointments, general information, and guide them through our services. Always maintain a professional yet friendly tone.",
  "zone": "LA",
  "buffer": 15,
  "color": "blue",
  "question": "How can I help you today?",
  "timezone": "America/Lima",
  "enable": true,
  "tags": [
    "health",
    "dentistry",
    "ia",
    "plazbot"
  ],
  "showInChat": false,
  "useToolCalling": true,
  "responseMode": "direct",
  "batchWaitSeconds": 3,
  "customAIConfig": false,
  "aiProviders": [
    {
      "provider": "openai",
      "model": "gpt-4o",
      "apiToken": "sk-...",
      "temperature": 0.7,
      "maxTokens": 1024,
      "isDefault": true
    }
  ],
  "version": "v2.0",
  "enableWidget": true,
  "darkWidget": true,
  "nameWidget": "Dental Assistant",
  "initialShowWidget": true,
  "examples": [
    { "value": "How to schedule an appointment?", "color": "green" },
    { "value": "What are your office hours?", "color": "blue" },
    { "value": "Do you accept insurance?", "color": "orange" },
    { "value": "Emergency contact information", "color": "gray" },
    { "value": "Location and directions", "color": "white" }
  ],
  "instructions": {
    "tone": "professional",
    "style": "short answers",
    "personality": "friendly",
    "objective": "help with clarity",
    "language": "es-419",
    "emojis": false,
    "preferredFormat": "plain text",
    "maxWords": 80,
    "avoidTopics": [
      "laboratory costs",
      "external claims",
      "specific medical diagnoses"
    ],
    "respondOnlyIfKnows": true,
    "maintainToneBetweenMessages": true,
    "greeting": "Hello, I am Máximo, your virtual assistant from Smiles Dental Clinic. How can I help you today?"
  },
  "person": {
    "name": "Máximo",
    "role": "Virtual customer service assistant",
    "speaksInFirstPerson": true,
    "isHuman": false
  },
  "fallbacks": {
    "noAnswer": "Sorry, I don't have information on that topic. Let me connect you with one of our specialists.",
    "serviceError": "There was a problem processing your request. Please try again later or contact us directly.",
    "doNotUnderstand": "Could you please repeat it in another way? I want to make sure I help you correctly."
  },
  "rules": {
    "doNotMentionPrices": false,
    "doNotDiagnose": true,
    "doNotRespondOutsideHours": "Our office hours are Monday to Saturday, from 8am to 6pm. For emergencies, please call our emergency line."
  },
  "channels": [
    {
      "channel": "whatsapp",
      "key": "+51987654321",
      "multianswer": false
    },
    {
      "channel": "telegram",
      "key": "smiles_clinic_bot",
      "multianswer": true
    }
  ],
  "services": [
    {
      "intent": "schedule_appointment",
      "reference": "Service for scheduling patient appointments at the dental clinic",
      "enabled": true,
      "method": "POST",
      "tags": ["appointment", "scheduling"],
      "endpoint": "https://api.smilesclinic.com/v1/appointments/schedule",
      "requiredFields": [
        {
          "name": "patient_name",
          "description": "Full name of the patient who wants to schedule the appointment",
          "promptHint": "Could you please provide your full name?",
          "type": "string"
        },
        {
          "name": "email",
          "description": "Patient's email address for appointment confirmation",
          "promptHint": "What's your email address for the appointment confirmation?",
          "type": "email"
        },
        {
          "name": "phone",
          "description": "Patient's phone number for contact",
          "promptHint": "Could you provide your phone number?",
          "type": "phone"
        },
        {
          "name": "preferred_date",
          "description": "Preferred date and time for the appointment",
          "promptHint": "What date and time would work best for your appointment?",
          "type": "datetime"
        },
        {
          "name": "service_type",
          "description": "Type of dental service needed",
          "promptHint": "What type of dental service do you need? (cleaning, consultation, etc.)",
          "type": "string"
        }
      ],
      "headers": {
        "Authorization": "Bearer {{clinic_api_key}}",
        "Content-Type": "application/json",
        "X-Clinic-ID": "smiles_001"
      },
      "bodyTemplate": {
        "patient": {
          "name": "{{patient_name}}",
          "email": "{{email}}",
          "phone": "{{phone}}"
        },
        "appointment": {
          "datetime": "{{preferred_date|format('yyyy-MM-dd HH:mm')}}",
          "service": "{{service_type}}",
          "timezone": "America/Lima"
        }
      },
      "bodySchema": {
        "patient_name": "string",
        "email": "string",
        "preferred_date": "date",
        "service_type": "string"
      },
      "responseMapping": {
        "confirmation_id": "$.data.appointment.id",
        "scheduled_date": "$.data.appointment.datetime",
        "status": "$.status",
        "doctor_name": "$.data.appointment.doctor.name",
        "conflict_reason": "$.error.reason"
      },
      "responseMessage": "Your appointment has been successfully scheduled for {{scheduled_date}} with Dr. {{doctor_name}}",
      "responseConditions": [
        {
          "condition": "$.status == 'confirmed'",
          "message": "¡Perfect! Your appointment has been confirmed for {{scheduled_date}} with Dr. {{doctor_name}}. We'll send you a reminder 24 hours before. Confirmation ID: {{confirmation_id}}",
          "nextService": "send_appointment_reminder"
        },
        {
          "condition": "$.status == 'conflict'",
          "message": "Sorry, that time slot is not available. {{conflict_reason}}. Would you like me to suggest other available times?",
          "nextService": "suggest_alternative_times"
        },
        {
          "condition": "$.status == 'error' && $.error.code == 'invalid_email'",
          "message": "The email address provided seems invalid. Could you please verify your email address?",
          "nextService": "verify_contact_info"
        },
        {
          "condition": "$.status == 'error' && $.error.code == 'past_date'",
          "message": "I cannot schedule appointments for past dates. Could you please choose a future date?"
        },
        {
          "condition": "$.status == 'pending'",
          "message": "Your appointment request is being reviewed. We'll contact you within 24 hours to confirm availability and finalize the details."
        }
      ],
      "action": "conversar_humano"
    },
    {
      "intent": "check_insurance",
      "reference": "Service to verify patient insurance coverage and benefits",
      "enabled": true,
      "method": "GET",
      "tags": ["insurance", "verification"],
      "endpoint": "https://api.smilesclinic.com/v1/insurance/verify",
      "requiredFields": [
        {
          "name": "insurance_provider",
          "description": "Name of the insurance company",
          "promptHint": "What's your insurance provider name?",
          "type": "string"
        },
        {
          "name": "policy_number",
          "description": "Insurance policy or member ID number",
          "promptHint": "Could you provide your policy or member ID number?",
          "type": "string"
        }
      ],
      "headers": {
        "Authorization": "Bearer {{insurance_api_key}}",
        "Content-Type": "application/json"
      },
      "responseMapping": {
        "coverage_status": "$.data.coverage.status",
        "deductible": "$.data.coverage.deductible",
        "copay": "$.data.coverage.copay",
        "covered_services": "$.data.coverage.services"
      },
      "responseMessage": "Your insurance verification is complete. Coverage status: {{coverage_status}}",
      "responseConditions": [
        {
          "condition": "$.data.coverage.status == 'active'",
          "message": "Great news! Your insurance is active. Your copay is ${{copay}} and your remaining deductible is ${{deductible}}. Covered services include: {{covered_services}}."
        },
        {
          "condition": "$.data.coverage.status == 'inactive'",
          "message": "It appears your insurance policy is not currently active. Please contact your insurance provider or we can discuss our self-pay options."
        },
        {
          "condition": "$.data.coverage.status == 'not_found'",
          "message": "I couldn't find your policy in our system. Please verify your insurance information or contact us directly for assistance."
        }
      ]
    }
  ],
  "actions": [
    {
      "intent": "assign_urgent_tag",
      "reference": "Tags patients as urgent when they mention emergency dental situations",
      "tags": ["emergency", "urgent"],
      "enabled": true,
      "responseMessage": "I've marked your case as urgent and notified our emergency team.",
      "responseJson": false,
      "responseExact": true,
      "action": [
        {
          "type": "action.tag",
          "value": "urgent_case"
        },
        {
          "type": "action.asign",
          "value": "emergency@smilesclinic.com"
        }
      ]
    },
    {
      "intent": "schedule_follow_up",
      "reference": "Automatically schedules follow-up appointments and assigns appropriate case management",
      "tags": ["follow-up", "scheduling"],
      "enabled": true,
      "responseMessage": "Your follow-up has been scheduled and assigned to our treatment coordinator.",
      "responseJson": false,
      "responseExact": false,
      "action": [
        {
          "type": "action.stage",
          "value": "follow_up_scheduled"
        },
        {
          "type": "action.segmentation",
          "value": "post_treatment_care"
        }
      ]
    },
    {
      "intent": "end_consultation",
      "reference": "Ends the AI consultation when the patient no longer needs assistance",
      "tags": ["consultation", "end"],
      "enabled": true,
      "responseMessage": "Thank you for contacting Smiles Dental Clinic. Have a great day!",
      "responseJson": false,
      "responseExact": true,
      "action": [
        {
          "type": "action.agentShutDown",
          "value": "true"
        }
      ]
    }
  ]
}
```

### **General** (`general`)

Campo

Descripción

**name**

Nombre del agente. Visible en el panel. `Requerido`

**prompt**

Instrucciones base para el comportamiento del agente. `Requerido`

**buffer**

Cantidad de mensajes que se mantienen como contexto. Rango: 3 a 20. `Requerido`

color

Color de presentación. Valores: `blue`, `orange`, `gray`, `green`, `white`.

question

Pregunta principal que se muestra en el portal.

description

Descripción general del agente.

**zone**

Zona donde opera el agente: `LA` (Latinoamérica) o `EU` (Europa). `Requerido`

timezone

Zona horaria. Ejemplo: `America/Lima`. [TimeZone Formats](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)

tags

Etiquetas internas para clasificar agentes.

examples

Preguntas sugeridas. Hasta 5.

showInChat

Si el agente se muestra en el widget/chat. (boolean)

enable

Si el agente esta habilitado o no. (boolean)

version

Version del agente (auto-incrementado). Formato: `v2.0`, `v2.1`, etc.

### **Configuracion de IA** (`AI Config`)

Campo

Tipo

Descripcion

useToolCalling

boolean

Si es `true`, usa el orquestador de Tool Calling para conversaciones mas naturales. Si es `false`, usa el orquestador clasico. Default: `false`.

responseMode

string

Modo de respuesta: `direct` (inmediato) o `batched` (espera mensajes consecutivos). Default: `direct`.

batchWaitSeconds

integer

Segundos de espera para acumular mensajes consecutivos (solo si `responseMode=batched`). Rango: 2-10. Default: 3.

customAIConfig

boolean

Si es `true`, usa los `aiProviders` configurados en el agente. Si es `false`, usa el token de OpenAI de la empresa. Default: `false`.

### **Proveedores de IA** (`aiProviders`)

Solo se usa cuando `customAIConfig` es `true`. Permite configurar multiples proveedores de IA.

Campo

Tipo

Descripcion

provider

string

Proveedor de IA: `openai`, `claude` (Anthropic), o `gemini` (Google).

model

string

Nombre del modelo: `gpt-4o`, `gpt-5`, `claude-3-5-sonnet-20241022`, `gemini-2.0-flash-exp`, etc.

apiToken

string

Token API del proveedor.

temperature

number

Controla la aleatoriedad en las respuestas (0-2). Default: 0.7.

maxTokens

integer

Maximo de tokens en la respuesta.

isDefault

boolean

Si hay multiples proveedores, cual usar por defecto.

### **Instrucciones** (`instructions`)

Las instrucciones se las puede colocar en español o en ingles, no hay ningun problema, la IA respetará el idioma que se le configura.

Campo

Tipo

Descripción

tone

string

Tono de comunicación: `professional`, `friendly`, etc.

style

string

Estilo de respuestas: `short answers`, `detailed`.

personality

string

Personalidad del agente.

objective

string

Objetivo principal del agente.

language

string

Idioma en que debe responder. Ver tabla de idiomas.

emojis

boolean

Si puede usar emojis.

preferredFormat

string

`plain text` o `markdown`.

maxWords

number

Máximo de palabras por respuesta.

avoidTopics

array

Lista de temas prohibidos.

respondOnlyIfKnows

boolean

Si debe evitar responder sin información confiable.

maintainToneBetweenMessages

boolean

Mantiene el mismo tono entre mensajes.

greeting

string

Mensaje de bienvenida.

**Opciones Objetive** "help with clarity" Enfocado en brindar respuestas claras "sell more" Promociona productos o servicios "support users" Ayuda a resolver problemas "guide actions" Brinda pasos concretos o instrucciones

**Opciones Personalidad** "friendly" Agradable y empático "serious" Reservado y directo "funny" Con toques de humor sutil "robotic" Más neutral, tipo IA técnica

**Opciones preferredFormat** "plain text" Texto simple "markdown" Permite negritas, listas, enlaces "html" Usado si se integrará en un entorno web

**Opciones Style** "short answers" Respuestas breves y directas "detailed" Respuestas explicativas, útiles para asistencia técnica "bullet points" Instrucciones u opciones en lista (ideal para pasos o listas) "conversational" Estilo fluido y natural, más humano

**Opciones Tono** "professional" Tono formal, educado, propio para empresas "friendly" Tono amigable, cercano, ideal para atención al cliente "casual" Informal, con lenguaje relajado y natural "neutral" Objetivo, sin inclinación emocional

### **Persona del Agente** (`person`)

Campo

Tipo

Descripción

name

string

Nombre que usará el agente.

role

string

Rol representado.

speaksInFirstPerson

boolean

Habla en primera persona.

isHuman

boolean

Simula ser una persona real.

### **Fallbacks**

Campo

Tipo

Descripción

noAnswer

string

Mensaje si no tiene respuesta.

serviceError

string

Mensaje de error de servicio.

doNotUnderstand

string

Mensaje si no entiende la consulta.

### **Reglas**

Campo

Tipo

Descripción

doNotMentionPrices

boolean

No hablar de precios.

doNotDiagnose

boolean

No hacer diagnósticos médicos.

doNotRespondOutsideHours

string

Mensaje fuera del horario definido. Trabaja junto con el campo de Timezone

### **Listados**

**Códigos de Idioma**

Valor

Descripción

es

Español general

es-419

Español latinoamericano neutral

es-ES

Español de España

en

Inglés general

en-US

Inglés estadounidense

en-GB

Inglés británico

fr

Francés general

fr-FR

Francés de Francia

pt-BR

Portugués brasileño

de

Alemán

**Códigos de Timezone**

Valor

Descripción

America/Los\_Angeles

Los Ángeles (UTC-08:00)

America/Mexico\_City

Ciudad de México (UTC-06:00)

America/New\_York

Nueva York (UTC-05:00)

America/Bogota

Bogotá (UTC-05:00)

America/Lima

Lima (UTC-05:00)

America/Sao\_Paulo

São Paulo (UTC-03:00)

Europe/London

Londres (UTC+00:00)

Europe/Madrid

Madrid (UTC+01:00)

Europe/Paris

París (UTC+01:00)

Europe/Berlin

Berlín (UTC+01:00)

Europe/Moscow

Moscú (UTC+03:00)

Asia/Dubai

Dubái (UTC+04:00)

Asia/Kolkata

Nueva Delhi (UTC+05:30)

Asia/Shanghai

Pekín (UTC+08:00)

Asia/Tokio

Tokio (UTC+09:00)