> For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt # Create a message template POST https://%7BYour_Space_Name%7D.signalwire.com/api/messaging/whatsapp/templates Content-Type: application/json Creates a message template and submits it to Meta for review. Approval typically takes from a few minutes to a few hours; poll the template's `template_status` until it becomes `approved`. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). Reference: https://signalwire.com/docs/apis/rest/whatsapp/create-whatsapp-template ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: signalwire-rest version: 1.0.0 paths: /api/messaging/whatsapp/templates: post: operationId: create_whatsapp_template summary: Create a message template description: >- Creates a message template and submits it to Meta for review. Approval typically takes from a few minutes to a few hours; poll the template's `template_status` until it becomes `approved`. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space). tags: - whatsAppTemplates parameters: - name: Authorization in: header description: >- SignalWire Basic Authentication using Project ID and API Token. The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password. Example: ``` Authorization: Basic base64(project_id:token) ``` required: true schema: type: string responses: '201': description: >- Response returned when a template is successfully created and submitted to Meta. content: application/json: schema: $ref: '#/components/schemas/WhatsAppTemplate' '400': description: The request is invalid. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode400' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode401' '422': description: The request contains invalid parameters. See errors for details. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode422' '500': description: An internal server error occurred. content: application/json: schema: $ref: '#/components/schemas/Types.StatusCodes.StatusCode500' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWhatsAppTemplateRequest' servers: - url: https://%7BYour_Space_Name%7D.signalwire.com description: SignalWire API components: schemas: uuid: type: string format: uuid description: Universal Unique Identifier. title: uuid WhatsAppTemplateCategory: type: string enum: - utility - marketing - authentication description: The category of a WhatsApp message template. title: WhatsAppTemplateCategory WhatsAppTemplateParameterFormat: type: string enum: - named - positional description: How a template's variable placeholders are referenced. title: WhatsAppTemplateParameterFormat WhatsAppTemplateComponent: type: object properties: type: type: string description: 'The component type: `HEADER`, `BODY`, `FOOTER`, or `BUTTONS`.' required: - type description: >- A template component. The `type` is one of `HEADER`, `BODY`, `FOOTER`, or `BUTTONS`. Additional fields depend on the component type — for example, a `BODY` carries `text`, while `BUTTONS` carries a `buttons` array. See the create example for the full shape. title: WhatsAppTemplateComponent CreateWhatsAppTemplateRequest: type: object properties: whatsapp_business_id: $ref: '#/components/schemas/uuid' description: >- The WhatsApp Business Account the template belongs to. List your accounts at `GET /api/messaging/whatsapp/businesses`. name: type: string description: >- The template name. Maximum 512 characters; lowercase letters, numbers, and underscores only. language: type: string description: The template language code. category: $ref: '#/components/schemas/WhatsAppTemplateCategory' description: The template category. parameter_format: $ref: '#/components/schemas/WhatsAppTemplateParameterFormat' description: How the template's variable placeholders are referenced. components: type: array items: $ref: '#/components/schemas/WhatsAppTemplateComponent' description: >- The template's components. Must include a `BODY` component. Each component is an object whose fields depend on its `type` — see the request example. required: - whatsapp_business_id - name - language - category - parameter_format - components description: Request body for creating a message template. title: CreateWhatsAppTemplateRequest WhatsAppTemplateStatus: type: string enum: - approved - archived - deleted - disabled - flagged - in_appeal - limit_exceeded - locked - paused - pending - reinstated - pending_deletion - rejected description: >- The Meta approval status of a template. A template must be `approved` before it can be used to send messages. title: WhatsAppTemplateStatus WhatsAppTemplate: type: object properties: id: $ref: '#/components/schemas/uuid' description: The SignalWire identifier of the template. name: type: string description: The template name. Lowercase letters, numbers, and underscores only. category: $ref: '#/components/schemas/WhatsAppTemplateCategory' description: The template category. components: type: array items: $ref: '#/components/schemas/WhatsAppTemplateComponent' description: The template's components (header, body, footer, buttons). language: type: string description: The template language code. parameter_format: $ref: '#/components/schemas/WhatsAppTemplateParameterFormat' description: How the template's variable placeholders are referenced. template_id: type: string description: Meta's identifier for the template. template_status: $ref: '#/components/schemas/WhatsAppTemplateStatus' description: The Meta approval status of the template. whatsapp_business_id: $ref: '#/components/schemas/uuid' description: >- The SignalWire identifier of the WhatsApp Business Account the template belongs to. created_at: type: string description: The date and time when the template was created. updated_at: type: string description: The date and time when the template was last updated. discarded_at: type: string description: The date and time when the template was discarded, if applicable. required: - id - name - category - components - language - parameter_format - template_id - template_status - whatsapp_business_id - created_at - updated_at description: A WhatsApp message template. title: WhatsAppTemplate TypesStatusCodesStatusCode400Error: type: string enum: - Bad Request title: TypesStatusCodesStatusCode400Error Types.StatusCodes.StatusCode400: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode400Error' required: - error description: The request is invalid. title: Types.StatusCodes.StatusCode400 TypesStatusCodesStatusCode401Error: type: string enum: - Unauthorized title: TypesStatusCodesStatusCode401Error Types.StatusCodes.StatusCode401: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error' required: - error description: Access is unauthorized. title: Types.StatusCodes.StatusCode401 Types.StatusCodes.RestApiErrorItem: type: object properties: type: type: string description: The category of error. code: type: string description: A specific error code. message: type: string description: A description of what caused the error. attribute: type: - string - 'null' description: The request parameter that caused the error, if applicable. url: type: string description: A link to documentation about this error. required: - type - code - message - url description: Details about a specific error. title: Types.StatusCodes.RestApiErrorItem Types.StatusCodes.StatusCode422: type: object properties: errors: type: array items: $ref: '#/components/schemas/Types.StatusCodes.RestApiErrorItem' description: List of validation errors. required: - errors description: The request contains invalid parameters. See errors for details. title: Types.StatusCodes.StatusCode422 TypesStatusCodesStatusCode500Error: type: string enum: - Internal Server Error title: TypesStatusCodesStatusCode500Error Types.StatusCodes.StatusCode500: type: object properties: error: $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error' required: - error description: An internal server error occurred. title: Types.StatusCodes.StatusCode500 securitySchemes: SignalWireBasicAuth: type: http scheme: basic description: >- SignalWire Basic Authentication using Project ID and API Token. The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password. Example: ``` Authorization: Basic base64(project_id:token) ``` ``` ## Examples **Request** ```json { "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "order_update", "language": "en_US", "category": "utility", "parameter_format": "positional", "components": [ { "type": "HEADER", "example": { "header_text": [ "Jane Smith" ] }, "format": "TEXT", "text": "Order Update for {{1}}" }, { "type": "BODY", "example": { "body_text": [ [ "ORD-9821", "out for delivery" ] ] }, "text": "Your order {{1}} is currently {{2}}." }, { "type": "FOOTER", "text": "Thank you for shopping with us." }, { "type": "BUTTONS", "buttons": [ { "text": "Track Order", "type": "QUICK_REPLY" }, { "text": "Contact Support", "type": "URL", "url": "https://example.com/support" } ] } ] } ``` **Response** ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "order_update", "category": "utility", "components": [ { "type": "BODY" } ], "language": "en_US", "parameter_format": "positional", "template_id": "1164792772433648", "template_status": "approved", "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "discarded_at": "2024-01-15T10:30:00Z" } ``` **SDK Code** ```python import requests url = "https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates" payload = { "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "order_update", "language": "en_US", "category": "utility", "parameter_format": "positional", "components": [ { "type": "HEADER", "example": { "header_text": ["Jane Smith"] }, "format": "TEXT", "text": "Order Update for {{1}}" }, { "type": "BODY", "example": { "body_text": [["ORD-9821", "out for delivery"]] }, "text": "Your order {{1}} is currently {{2}}." }, { "type": "FOOTER", "text": "Thank you for shopping with us." }, { "type": "BUTTONS", "buttons": [ { "text": "Track Order", "type": "QUICK_REPLY" }, { "text": "Contact Support", "type": "URL", "url": "https://example.com/support" } ] } ] } headers = { "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, auth=("", "")) print(response.json()) ``` ```javascript const url = 'https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates'; const credentials = btoa(":"); const options = { method: 'POST', headers: { Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json' }, body: '{"whatsapp_business_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","name":"order_update","language":"en_US","category":"utility","parameter_format":"positional","components":[{"type":"HEADER","example":{"header_text":["Jane Smith"]},"format":"TEXT","text":"Order Update for {{1}}"},{"type":"BODY","example":{"body_text":[["ORD-9821","out for delivery"]]},"text":"Your order {{1}} is currently {{2}}."},{"type":"FOOTER","text":"Thank you for shopping with us."},{"type":"BUTTONS","buttons":[{"text":"Track Order","type":"QUICK_REPLY"},{"text":"Contact Support","type":"URL","url":"https://example.com/support"}]}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates" payload := strings.NewReader("{\n \"whatsapp_business_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"name\": \"order_update\",\n \"language\": \"en_US\",\n \"category\": \"utility\",\n \"parameter_format\": \"positional\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"example\": {\n \"header_text\": [\n \"Jane Smith\"\n ]\n },\n \"format\": \"TEXT\",\n \"text\": \"Order Update for {{1}}\"\n },\n {\n \"type\": \"BODY\",\n \"example\": {\n \"body_text\": [\n [\n \"ORD-9821\",\n \"out for delivery\"\n ]\n ]\n },\n \"text\": \"Your order {{1}} is currently {{2}}.\"\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thank you for shopping with us.\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"text\": \"Track Order\",\n \"type\": \"QUICK_REPLY\"\n },\n {\n \"text\": \"Contact Support\",\n \"type\": \"URL\",\n \"url\": \"https://example.com/support\"\n }\n ]\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.SetBasicAuth("", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request.basic_auth("", "") request["Content-Type"] = 'application/json' request.body = "{\n \"whatsapp_business_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"name\": \"order_update\",\n \"language\": \"en_US\",\n \"category\": \"utility\",\n \"parameter_format\": \"positional\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"example\": {\n \"header_text\": [\n \"Jane Smith\"\n ]\n },\n \"format\": \"TEXT\",\n \"text\": \"Order Update for {{1}}\"\n },\n {\n \"type\": \"BODY\",\n \"example\": {\n \"body_text\": [\n [\n \"ORD-9821\",\n \"out for delivery\"\n ]\n ]\n },\n \"text\": \"Your order {{1}} is currently {{2}}.\"\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thank you for shopping with us.\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"text\": \"Track Order\",\n \"type\": \"QUICK_REPLY\"\n },\n {\n \"text\": \"Contact Support\",\n \"type\": \"URL\",\n \"url\": \"https://example.com/support\"\n }\n ]\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates") .basicAuth("", "") .header("Content-Type", "application/json") .body("{\n \"whatsapp_business_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"name\": \"order_update\",\n \"language\": \"en_US\",\n \"category\": \"utility\",\n \"parameter_format\": \"positional\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"example\": {\n \"header_text\": [\n \"Jane Smith\"\n ]\n },\n \"format\": \"TEXT\",\n \"text\": \"Order Update for {{1}}\"\n },\n {\n \"type\": \"BODY\",\n \"example\": {\n \"body_text\": [\n [\n \"ORD-9821\",\n \"out for delivery\"\n ]\n ]\n },\n \"text\": \"Your order {{1}} is currently {{2}}.\"\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thank you for shopping with us.\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"text\": \"Track Order\",\n \"type\": \"QUICK_REPLY\"\n },\n {\n \"text\": \"Contact Support\",\n \"type\": \"URL\",\n \"url\": \"https://example.com/support\"\n }\n ]\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates', [ 'body' => '{ "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "order_update", "language": "en_US", "category": "utility", "parameter_format": "positional", "components": [ { "type": "HEADER", "example": { "header_text": [ "Jane Smith" ] }, "format": "TEXT", "text": "Order Update for {{1}}" }, { "type": "BODY", "example": { "body_text": [ [ "ORD-9821", "out for delivery" ] ] }, "text": "Your order {{1}} is currently {{2}}." }, { "type": "FOOTER", "text": "Thank you for shopping with us." }, { "type": "BUTTONS", "buttons": [ { "text": "Track Order", "type": "QUICK_REPLY" }, { "text": "Contact Support", "type": "URL", "url": "https://example.com/support" } ] } ] }', 'headers' => [ 'Content-Type' => 'application/json', ], 'auth' => ['', ''], ]); echo $response->getBody(); ``` ```csharp using RestSharp; using RestSharp.Authenticators; var client = new RestClient("https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates"); client.Authenticator = new HttpBasicAuthenticator("", ""); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"whatsapp_business_id\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"name\": \"order_update\",\n \"language\": \"en_US\",\n \"category\": \"utility\",\n \"parameter_format\": \"positional\",\n \"components\": [\n {\n \"type\": \"HEADER\",\n \"example\": {\n \"header_text\": [\n \"Jane Smith\"\n ]\n },\n \"format\": \"TEXT\",\n \"text\": \"Order Update for {{1}}\"\n },\n {\n \"type\": \"BODY\",\n \"example\": {\n \"body_text\": [\n [\n \"ORD-9821\",\n \"out for delivery\"\n ]\n ]\n },\n \"text\": \"Your order {{1}} is currently {{2}}.\"\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thank you for shopping with us.\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"text\": \"Track Order\",\n \"type\": \"QUICK_REPLY\"\n },\n {\n \"text\": \"Contact Support\",\n \"type\": \"URL\",\n \"url\": \"https://example.com/support\"\n }\n ]\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let credentials = Data(":".utf8).base64EncodedString() let headers = [ "Authorization": "Basic \(credentials)", "Content-Type": "application/json" ] let parameters = [ "whatsapp_business_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "order_update", "language": "en_US", "category": "utility", "parameter_format": "positional", "components": [ [ "type": "HEADER", "example": ["header_text": ["Jane Smith"]], "format": "TEXT", "text": "Order Update for {{1}}" ], [ "type": "BODY", "example": ["body_text": [["ORD-9821", "out for delivery"]]], "text": "Your order {{1}} is currently {{2}}." ], [ "type": "FOOTER", "text": "Thank you for shopping with us." ], [ "type": "BUTTONS", "buttons": [ [ "text": "Track Order", "type": "QUICK_REPLY" ], [ "text": "Contact Support", "type": "URL", "url": "https://example.com/support" ] ] ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://{your_space_name}.signalwire.com/api/messaging/whatsapp/templates")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```