> ## Documentation Index > Fetch the complete documentation index at: https://help.texterchat.com/llms.txt > Use this file to discover all available pages before exploring further. # Create New Template > This endpoint is the first of three required to create and submit a new template. **Required token scopes:** `Manage WhatsApp templates` When a template is first created, it exists only locally and is not yet visible to WhatsApp. The template entity is internal, so it has properties unknown to WhatsApp such as the reply action, bot node, and departments. After creating a template, the next step is to **Create or Update Localization**, which defines all the properties required by WhatsApp - including the language, components (header, body, footer, buttons) and example variable values. Finally, once both the template **and** its localization have been created, you can **Submit the Template for Approval**. If you don't specify a template `name`, one is generated automatically - save the generated name from the response to use when creating a localization and submitting. ## OpenAPI ````yaml he/api-reference/openapi.json POST /whatsapp/templates/{accountId} openapi: 3.1.0 info: title: Texter API V2 version: 2.0.0 description: >- The **Texter API** lets your developers control the Texter platform programmatically: - Manage and send your WhatsApp template messages - Retrieve chats by ID or by various filters - Assign and resolve conversations - Send session messages into active chats - Manage labels - Monitor and resolve channel health issues - Subscribe to real-time webhook events - Manage quick replies (coming soon) For any questions please contact [Texter Support](https://wa.me/972586640430). contact: name: Texter Support url: https://wa.me/972586640430 servers: - url: https://{projectID}.texterchat.com/server/api/v2 description: Your Texter environment. Replace projectID with your project subdomain variables: projectID: default: demo description: >- Your unique project subdomain. If your environment URL is https://demo.texterchat.com, your projectID is "demo" security: - bearerAuth: [] tags: - name: Manage Templates description: >- Create, localize, submit, update, delete and send WhatsApp template messages, and retrieve approved templates for your connected WhatsApp accounts. **Suggested token for this group** - create one API token with the scopes: *Send template messages*, *View template messages*, *Manage WhatsApp templates*, *Manage all chats*, *List all chats* (the last two also cover the Templates Subscriptions group). Each endpoint below also lists the exact scopes it needs. - name: Templates Subscriptions description: >- Manage recipient subscriptions for WhatsApp template messages - unsubscribe or resubscribe recipients, and list unsubscribed users across all channels or for a specific account. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*. Each endpoint below also lists the exact scopes it needs. - name: Messages description: >- Retrieve message history from a chat, or send new session messages - text, media, buttons, lists, contact cards and locations - within the active WhatsApp 24-hour session window. **Suggested token for this group** - scopes: *Send session message*, *View all chats*. Each endpoint below also lists the exact scopes it needs. - name: Chats description: >- Fetch chat details, search conversations, update chat properties, assign or resolve chats, and manage their CRM metadata. **Suggested token for this group** - scopes: *Manage all chats*, *List all chats*, *Send session message*. Each endpoint below also lists the exact scopes it needs. - name: Labels description: >- Create and edit labels, assign or remove them from chats, retrieve label data, or delete labels from your inbox. **Suggested token for this group** - scopes: *Manage labels*, *Manage all chats* (needed for managing labels on chats). Each endpoint below also lists the exact scopes it needs. - name: Channels description: >- Monitor and maintain the health of connected messaging channels - retrieve active channel health problems, filter them by severity or account, and mark issues as resolved. **Suggested token for this group** - scopes: *Manage channels*. Each endpoint below also lists the exact scopes it needs. - name: Quick Replies description: >- Manage quick replies - prepared messages agents can send into matching chats with one click. Quick replies marked with `aiQuickReply` client metadata appear as **AI suggestions** in the Texter inbox (see Create Quick Reply for the full flow). **Suggested token for this group** - scopes: *View quick replies*, *Manage quick replies*. Each endpoint below also lists the exact scopes it needs. - name: Files description: >- Generate public access links to media files stored in Texter. **Suggested token for this group** - scopes: *View all files*, *View all chats* (both required). Each endpoint below also lists the exact scopes it needs. - name: Subscribe to Events description: >- Register webhooks for events occurring in your Texter environment. Under the hood this uses **Scenarios** - a workflow automation feature within Texter. To make integration easy, pre-defined templates are provided: import a scenario JSON, plug in your webhook URL and user UID, and the subscription is active. See the **Webhook Events** pages for the payload your URL receives for each event. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*. Each endpoint below also lists the exact scopes it needs. If the provided templates don't satisfy your needs, contact [Texter Support](https://wa.me/972586640430) and we'll gladly help modify any triggers, conditions or actions for your webhook. - name: Scenarios (Advanced) description: >- Full programmatic control over scenarios for advanced automations: create scenarios from scratch, copy them, edit drafts, publish revisions, inspect execution runs, and discover the available building blocks (events, conditions, loaders, actions). For plain webhook subscriptions, the **Subscribe to Events** group with its ready-made templates is the simpler path. **Suggested token for this group** - scopes: *View scenarios*, *Create scenarios*, *Edit scenarios*, *Delete scenarios*, *Activate/inactivate scenarios*, *Manage scenarios on behalf of user*, *View scenarios runs*. Each endpoint below also lists the exact scopes it needs. paths: /whatsapp/templates/{accountId}: post: tags: - Manage Templates summary: Create New Template description: >- This endpoint is the first of three required to create and submit a new template. **Required token scopes:** `Manage WhatsApp templates` When a template is first created, it exists only locally and is not yet visible to WhatsApp. The template entity is internal, so it has properties unknown to WhatsApp such as the reply action, bot node, and departments. After creating a template, the next step is to **Create or Update Localization**, which defines all the properties required by WhatsApp - including the language, components (header, body, footer, buttons) and example variable values. Finally, once both the template **and** its localization have been created, you can **Submit the Template for Approval**. If you don't specify a template `name`, one is generated automatically - save the generated name from the response to use when creating a localization and submitting. operationId: create-template parameters: - name: accountId in: path required: true schema: type: string description: >- The account ID of the channel in Texter. For WhatsApp channels this is the phone number connected to the account (e.g. `972586640430`) requestBody: required: true content: application/json: schema: type: object properties: title: type: string description: Internal title shown in Texter category: type: string enum: - MARKETING - UTILITY description: >- WhatsApp template category. WhatsApp may adjust this value upon submission based on the template's semantic classification chatStatus: type: integer enum: - 0 - 1 - 2 - 3 description: >- The chat status after the recipient replies to the template: `0` = BOT, `1` = PENDING, `2` = ASSIGNED, `3` = RESOLVED usage: type: string enum: - inbox - bulk description: >- Whether this template is intended to be sent individually (`inbox`) or in bulk (`bulk`) name: type: string pattern: ^[a-zA-Z0-9_]+$ description: >- The template name (which serves as its ID). Auto-generated if not specified. Must be unique per account. Only letters, numbers and underscores are allowed isDefault: type: boolean description: Defaults to `false`. Only one template can be the default departments: type: array items: type: string description: Department IDs that have access to this template setBotNode: type: string description: >- If `chatStatus` is `0` (BOT), the bot starts running from this specific node when the recipient replies. Must be an existing node in the channel's bot responsibleAgent: type: string description: >- Assign the chat to this agent (agent email in Texter) after the recipient replies. Can't be combined with `responsibleDepartment` responsibleDepartment: type: string description: >- Assign the chat to this department (department ID from Texter) after the recipient replies. Can't be combined with `responsibleAgent` replyText: type: string description: >- Text sent automatically when the recipient replies to the template required: - title - category - chatStatus - usage examples: Simple template: value: title: Example Template category: MARKETING chatStatus: 1 usage: inbox Template routed to bot: value: title: Template to Bot category: UTILITY chatStatus: 0 usage: bulk setBotNode: new_holiday_campaign Advanced template: value: title: Advanced Example category: MARKETING chatStatus: 2 usage: inbox name: send_receipt isDefault: true departments: - business - cf9055b2-95f5-4c08-b4ac-7d87298873c0 responsibleAgent: demo@texterchat.com replyText: Thanks for your purchase! Can we help with anything else? Bulk template routed to a department: value: title: Holiday campaign category: MARKETING chatStatus: 1 usage: bulk responsibleDepartment: customer_service replyText: תודה שפנית אלינו! נציג מצוות שירות הלקוחות יחזור אליך בהקדם. responses: '200': description: >- The newly created template object. Field-by-field reference: [The Template object](/he/api-reference/objects/template) content: application/json: schema: $ref: '#/components/schemas/Template' examples: Created template: value: _id: 690868f7962e17ab3033f91b name: inbox_marketing_95 channelInfo: name: whatsapp accountId: '972509876543' chatStatus: 1 created: 1762158839563 departments: [] isDefault: false localizationDrafts: {} provider_template: name: inbox_marketing_95 category: MARKETING localizations: [] metadata: {} title: Example Template updatedAt: '2025-11-03T08:33:59.563Z' usage: inbox '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: data/chatStatus must be equal to one of the allowed values '401': description: Missing or invalid token, or missing required scope components: schemas: Template: type: object description: >- A WhatsApp template in Texter, including internal behavior (chat routing rules, departments, defaults) and provider state (WhatsApp approval status, localized content) properties: _id: type: string description: Unique identifier of the template in Texter example: 6891bb93481ccea320113a91 name: type: string description: Internal template name (also used as the template ID in API calls) example: bulk_marketing_272 title: type: string description: Human-readable title shown in Texter's UI usage: type: string enum: - inbox - bulk description: >- How this template is intended to be sent: `inbox` (1-to-1) or `bulk` (broadcast) chatStatus: allOf: - $ref: '#/components/schemas/ChatStatus' description: >- Status the chat moves to after the recipient replies to this template created: type: number description: When the template was created (epoch ms) updatedAt: type: string format: date-time departments: type: array items: type: string description: Department IDs allowed to use this template. Can be empty isDefault: type: boolean description: >- Whether this is the default template for the account. Only one template can be default setBotNode: type: string description: Bot node to trigger after reply, if chatStatus routes to bot bot: type: string description: Specific bot to run after reply, if chatStatus routes to bot replyText: type: string description: Text automatically sent when the recipient replies to the template responsibleAgent: type: string description: Agent (email) the chat is assigned to after the recipient replies responsibleDepartment: type: string description: Department ID the chat is assigned to after the recipient replies attachedFile: type: object description: File automatically sent when the recipient replies, when configured properties: name: type: string url: type: string provider: type: string description: >- Channel adapter that owns this template (relevant when multiple WhatsApp account types are connected) channelInfo: type: object description: The channel account this template belongs to properties: name: allOf: - $ref: '#/components/schemas/ChannelName' accountId: type: string description: For WhatsApp, the business phone number connected to Texter example: '972586640430' provider_template: type: object description: The template as registered with WhatsApp properties: name: type: string description: >- Template name as registered with WhatsApp. Typically matches `name` category: type: string description: >- WhatsApp template category: `MARKETING` or `UTILITY`. WhatsApp may change it on approval example: MARKETING localizations: type: array items: $ref: '#/components/schemas/TemplateLocalization' description: >- All localizations known to WhatsApp. If empty while `localizationDrafts` has data, the template exists in Texter but was not yet submitted/approved metadata: type: object additionalProperties: true defaults: type: object description: >- Default send values by language code, prefilled when sending the template if the caller does not provide overrides additionalProperties: type: object properties: body: type: array items: type: string description: Default BODY variable values header: type: object description: >- Default header media: `type` + `url` (+ `filename` for documents) properties: type: type: string enum: - image - video - document url: type: string filename: type: string buttons: type: array description: Default button payloads (e.g. a default dynamic-URL value) items: type: object properties: type: type: string enum: - quick_reply - url - flow - voice_call payload: type: string localizationDrafts: type: object description: >- Map of language code to draft localization (created but not yet submitted/approved) additionalProperties: type: object properties: language: type: string components: type: array items: $ref: '#/components/schemas/TemplateComponent' metadata: type: object additionalProperties: true ErrorResponse: type: object properties: error: type: string description: Human-readable error message required: - error ChatStatus: type: integer enum: - 0 - 1 - 2 - 3 - 4 description: >- Chat status: `0` = BOT (handled by bot), `1` = PENDING (waiting for an agent), `2` = ASSIGNED (shown as "Taken" in Texter), `3` = RESOLVED, `4` = BULK ChannelName: type: string enum: - whatsapp - messenger - instagram - website_chat - email - sms description: Messaging channel type TemplateLocalization: type: object additionalProperties: true description: >- One localization (language variant) of a template as seen by WhatsApp. Besides the fields below, the WhatsApp provider passes through raw fields per account type - WhatsApp Cloud accounts add `id`, `name`, `category`, `previous_category`, `parameter_format`; other providers add `createdAt`, `lastUpdated`, `qualityScore` properties: status: type: string enum: - REQUESTED - SUBMIT_FAILED - PENDING - APPROVED - REJECTED - DELETION_PENDING - DELETED - SUBMITTED description: Approval status of this localization rejectionReason: type: string example: NONE language: type: string description: >- WhatsApp locale code, e.g. `he`, `en`, `en_US`, `pt_BR` (71 locales supported) example: he components: type: array items: $ref: '#/components/schemas/TemplateComponent' metadata: type: object additionalProperties: true description: Channel-specific metadata, when present createdAt: type: string format: date-time description: Provider-specific (not present on WhatsApp Cloud accounts) lastUpdated: type: string format: date-time description: Provider-specific (not present on WhatsApp Cloud accounts) qualityScore: type: object description: >- WhatsApp quality rating. Provider-specific (not present on WhatsApp Cloud accounts) properties: score: type: string description: Quality tier, e.g. `UNKNOWN`, `GREEN`, `YELLOW`, `RED` reasons: type: array items: type: string nullable: true example: - High block rate TemplateComponent: type: object description: A WhatsApp template component (HEADER / BODY / FOOTER / BUTTONS) properties: type: type: string enum: - HEADER - BODY - FOOTER - BUTTONS text: type: string description: >- Text content for BODY or FOOTER. BODY text supports numbered variables (`{{1}}`, `{{2}}`...) and is limited by WhatsApp to ~1024 characters for MARKETING templates and ~550 characters for UTILITY templates format: type: string enum: - IMAGE - VIDEO - DOCUMENT - LOCATION description: Header format. Only relevant to HEADER components example: type: object description: Example values required by WhatsApp for approval properties: header_handle: type: array items: type: string description: >- Required for media headers: an array with exactly one HTTP(S) URL used as the header example media body_text: type: array items: type: array items: type: string description: >- Example values for `{{1}}`, `{{2}}`, etc. in BODY. **Required when the body text contains variables** - must match the variable count and order buttons: type: array description: >- Button definitions. Only relevant to BUTTONS components. WhatsApp allows either up to 3 `QUICK_REPLY` buttons, **or** up to 2 call-to-action buttons (mix of `URL`, `PHONE_NUMBER`, `FLOW`) - the two groups cannot be mixed items: type: object properties: type: type: string enum: - QUICK_REPLY - URL - PHONE_NUMBER - FLOW text: type: string description: >- Button label shown to the recipient. For FLOW buttons: max 25 characters url: type: string description: >- URL for `URL` buttons. May contain **at most one** variable, which must be `{{1}}` and must appear at the end of the URL phone_number: type: string description: Phone number for `PHONE_NUMBER` buttons (E.164) flow_id: type: string description: Published Flow ID from Meta, for `FLOW` buttons flow_action: type: string enum: - navigate - data_exchange description: How the Flow opens. Defaults to `navigate` navigate_screen: type: string description: >- The screen `id` in the Flow JSON to open first. Required when `flow_action` is `navigate`. Case-sensitive example: type: object properties: url: type: string description: >- Required by WhatsApp when `url` contains a variable: a fully-resolved example URL that must start with the exact same literal prefix as `url` (everything before `{{1}}`) securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token generated in Texter: gear icon → Developers → API Tokens. When creating a token, assign it the scopes required by the endpoints you plan to call - each endpoint lists its required scopes. ````