> ## Documentation Index > Fetch the complete documentation index at: https://kapso-1adbad2d.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Create a new WhatsApp template > Creates a new draft template that can be later submitted to WhatsApp for approval. When a whatsapp_config_id (or customer_id) is provided, the template is automatically associated with all production configs that share the same WhatsApp Business Account (WABA). Note: You cannot associate templates with configs from different WABAs. Attempting to do so will return a 422 validation error. ## OpenAPI ````yaml api/legacy/openapi-whatsapp.yaml post /whatsapp_templates openapi: 3.0.3 info: title: Kapso External API - WhatsApp API description: >- API for programmatically interacting with Kapso agents, executions, and WhatsApp conversations. This specification includes only WhatsApp API endpoints. version: 1.0.0 contact: name: Kapso Support servers: - url: https://app.kapso.ai/api/v1 description: Production server security: - ApiKeyAuth: [] paths: /whatsapp_templates: post: tags: - WhatsApp Templates summary: Create a new WhatsApp template description: > Creates a new draft template that can be later submitted to WhatsApp for approval. When a whatsapp_config_id (or customer_id) is provided, the template is automatically associated with all production configs that share the same WhatsApp Business Account (WABA). Note: You cannot associate templates with configs from different WABAs. Attempting to do so will return a 422 validation error. operationId: createWhatsappTemplate requestBody: required: true content: application/json: schema: type: object required: - template properties: template: type: object required: - name - language_code - category - components properties: name: type: string description: Template name (must be unique per language) example: appointment_reminder language_code: type: string description: Language code (e.g., 'en_US') example: en_US category: type: string description: Template category enum: - MARKETING - UTILITY - AUTHENTICATION example: UTILITY parameter_format: type: string description: >- Parameter format - NAMED for named parameters like {{customer_name}}, POSITIONAL for {{1}}, {{2}} enum: - NAMED - POSITIONAL default: POSITIONAL example: NAMED components: type: array description: >- Template components structure (array of component objects) items: type: object properties: type: type: string enum: - HEADER - BODY - FOOTER - BUTTONS description: Component type format: type: string enum: - TEXT - IMAGE - VIDEO - DOCUMENT - LOCATION description: Format for HEADER components text: type: string description: Text content of the component example: type: object description: Example media for HEADER components properties: header_handle: type: array items: type: string buttons: type: array description: Array of buttons for BUTTONS component items: type: object properties: type: type: string enum: - QUICK_REPLY - URL - PHONE_NUMBER text: type: string url: type: string description: URL for URL type buttons phone_number: type: string description: Phone number for PHONE_NUMBER type buttons whatsapp_config_id: type: string format: uuid description: > Optional: Specific WhatsApp phone number configuration to associate with template. Templates can be associated with multiple phone numbers (WhatsApp configs). Association options: - If whatsapp_config_id provided: associates with that specific phone number only - If customer_id provided: associates with ALL production configs of that customer - If neither provided: associates with ALL production configs of the project customer_id: type: string format: uuid description: > Optional: Customer whose WhatsApp configs to associate with template. When provided, the template will be associated with ALL production WhatsApp configs (phone numbers) belonging to this customer, making it available for sending from any of them. examples: simple_text_template: summary: Simple text-only template description: >- Basic template with only a BODY component containing plain text value: template: name: welcome_message language_code: en_US category: UTILITY components: - type: BODY text: >- Welcome to our service! We're excited to have you on board. template_with_positional_params: summary: Template with positional parameters description: >- Template using numbered placeholders ({{1}}, {{2}}) - legacy format value: template: name: appointment_reminder_legacy language_code: en_US category: UTILITY parameter_format: POSITIONAL components: - type: BODY text: >- Hello {{1}}, your appointment is scheduled for {{2}} at {{3}}. Please arrive 15 minutes early. example: body_text: - - John Smith - December 15th - 2:30 PM template_with_named_parameters: summary: Template with named parameters description: >- Template using named placeholders like {{customer_name}}, {{date}} for dynamic content value: template: name: appointment_reminder language_code: en_US category: UTILITY parameter_format: NAMED components: - type: BODY text: >- Hello {{customer_name}}, your appointment is scheduled for {{appointment_date}} at {{appointment_time}}. Please arrive 15 minutes early. example: body_text_named_params: - param_name: customer_name example: John Smith - param_name: appointment_date example: December 15th - param_name: appointment_time example: 2:30 PM template_with_header_footer: summary: Template with header, body, and footer (named parameters) description: >- Complete template structure with all text components using named parameters value: template: name: order_confirmation language_code: en_US category: UTILITY parameter_format: NAMED components: - type: HEADER format: TEXT text: 'Order Confirmation #{{order_id}}' example: header_text_named_params: - param_name: order_id example: ORD-2024-001 - type: BODY text: >- Thank you {{customer_name}}! Your order #{{order_number}} has been confirmed and will be delivered by {{delivery_date}}. example: body_text_named_params: - param_name: customer_name example: Jane Doe - param_name: order_number example: ORD-2024-001 - param_name: delivery_date example: December 20th - type: FOOTER text: Questions? Contact support@example.com template_with_image_header: summary: Template with image header (named parameters) description: >- Marketing template with an image header and body text using named parameters value: template: name: seasonal_sale language_code: en_US category: MARKETING parameter_format: NAMED components: - type: HEADER format: IMAGE example: header_handle: - 4::aW... - type: BODY text: >- 🎉 {{season_name}} Sale is here! Get {{discount_percentage}} off on all items. Use code: {{promo_code}} example: body_text_named_params: - param_name: season_name example: Summer - param_name: discount_percentage example: 30% - param_name: promo_code example: SUMMER30 - type: FOOTER text: Valid until August 31st template_with_buttons: summary: Template with quick reply buttons (named parameters) description: >- Interactive template with body text and quick reply buttons using named parameters value: template: name: feedback_request language_code: en_US category: UTILITY parameter_format: NAMED components: - type: BODY text: >- Hi {{customer_name}}, how was your experience with our service today? example: body_text_named_params: - param_name: customer_name example: John - type: BUTTONS buttons: - type: QUICK_REPLY text: Excellent - type: QUICK_REPLY text: Good - type: QUICK_REPLY text: Needs Improvement template_with_url_button: summary: Template with URL button (named parameters) description: >- Template with a call-to-action URL button using named parameters value: template: name: track_order language_code: en_US category: UTILITY parameter_format: NAMED components: - type: BODY text: >- Your order #{{order_id}} is on its way! Track your delivery in real-time. example: body_text_named_params: - param_name: order_id example: ORD-2024-123 - type: BUTTONS buttons: - type: URL text: Track Order url: https://example.com/track/{{order_id}} example: - ORD-2024-123 template_with_phone_button: summary: Template with phone number button description: Customer support template with a phone number button value: template: name: support_contact language_code: en_US category: UTILITY components: - type: BODY text: >- Hi {{1}}, we noticed you might need help with your recent purchase. Our support team is ready to assist you. example: body_text: - - John - type: BUTTONS buttons: - type: PHONE_NUMBER text: Call Support phone_number: '+1234567890' marketing_template_complete: summary: Complete marketing template description: >- Full-featured marketing template with video header, body, footer, and multiple buttons value: template: name: product_launch language_code: en_US category: MARKETING components: - type: HEADER format: VIDEO example: header_handle: - 4::aW... - type: BODY text: >- 🚀 Introducing {{1}}! Be among the first to experience {{2}}. Limited time offer: {{3}} off for early adopters! example: body_text: - - Product X - innovation - 25% - type: FOOTER text: Offer valid until December 31st - type: BUTTONS buttons: - type: QUICK_REPLY text: Get Offer - type: URL text: Learn More url: https://example.com/products/{{1}} example: - product-x authentication_template: summary: Authentication template with OTP (positional) description: Two-factor authentication template using positional parameters value: template: name: otp_verification language_code: en_US category: AUTHENTICATION parameter_format: POSITIONAL components: - type: BODY text: >- Your verification code is {{1}}. This code will expire in {{2}} minutes. Do not share this code with anyone. example: body_text: - - '123456' - '10' - type: FOOTER text: Didn't request this? Contact security@example.com authentication_template_named: summary: Authentication template with OTP (named parameters) description: Two-factor authentication template using named parameters value: template: name: otp_verification_named language_code: en_US category: AUTHENTICATION parameter_format: NAMED components: - type: BODY text: >- Your verification code is {{otp_code}}. This code will expire in {{expiry_minutes}} minutes. Do not share this code with anyone. example: body_text_named_params: - param_name: otp_code example: '123456' - param_name: expiry_minutes example: '10' - type: FOOTER text: Didn't request this? Contact security@example.com spanish_template: summary: Spanish language template description: Template in Spanish for international customers value: template: name: bienvenida language_code: es_ES category: UTILITY components: - type: HEADER format: TEXT text: ¡Bienvenido! - type: BODY text: >- Hola {{1}}, gracias por unirte a nuestro servicio. Tu cuenta ha sido creada exitosamente. example: body_text: - - María - type: FOOTER text: ¿Necesitas ayuda? Contáctanos responses: '201': description: Template created successfully content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WhatsappTemplate' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Validation error content: application/json: schema: type: object properties: error: type: string example: Invalid template errors: type: array items: type: string example: - Name can't be blank - Language code is not valid '500': description: Internal server error content: application/json: schema: type: object properties: status: type: string example: error message: type: string example: 'Failed to create template: Internal Error' components: schemas: WhatsappTemplate: type: object properties: id: type: string format: uuid example: template-123abc name: type: string example: appointment_reminder language_code: type: string example: en_US category: type: string enum: - MARKETING - UTILITY - AUTHENTICATION example: UTILITY status: type: string enum: - draft - submitted - approved - rejected - disabled - removed example: approved content: type: string example: Hello {{1}}, your appointment is confirmed for {{2}}. parameter_count: type: integer example: 2 business_account_id: type: string nullable: true example: '123456789012345' description: WhatsApp Business Account ID this template belongs to whatsapp_config_ids: type: array items: type: string format: uuid example: - config-123abc - config-456def description: Array of WhatsApp config IDs this template is associated with components: type: array description: Raw WhatsApp template components structure items: type: object properties: type: type: string enum: - HEADER - BODY - FOOTER - BUTTONS format: type: string enum: - TEXT - IMAGE - VIDEO - DOCUMENT - LOCATION text: type: string example: type: object buttons: type: array items: type: object metadata: type: object description: Additional metadata about the template created_at: type: string format: date-time updated_at: type: string format: date-time Error: type: object properties: error: type: string example: Resource not found status: type: integer example: 404 message: type: string example: The requested resource could not be found securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key required for all endpoints ````