---
updatedAt: 2026-06-26T07:00:03.000Z
agentTools:
  projectIndex: https://partner-docs.gupshup.io/llms.txt
---

# Media-Based Message Template

Use this API to send a media based  message as template.

> 📘 Note:
>
> 1. Sending Marketing Templates through MM Lite for enhanced delivery optimization. For more details, refer to [*MM Lite*](https://partner-docs.gupshup.io/docs/marketing-messages-lite-mm-lite-api) document.
> 2. Use the `recipient` parameter only when BSUID is enabled for the app.
> 3. When both `to` and `recipient` fields are used in the payload, the `to` field gets the priority.

## Request Parameters

| Key                | Value                     | Description                                                 | Data type | Required/Optional                                                                                  | Constraints                                               |
| :----------------- | :------------------------ | :---------------------------------------------------------- | :-------- | :------------------------------------------------------------------------------------------------- | :-------------------------------------------------------- |
| Authorization      | \{\{PARTNER\_APP\_TOKEN}} | Access Token for the application                            | String    | Required                                                                                           | Should be a valid Partner App Access Token.               |
| appId              | \{\{APP\_ID}}             | App ID to fetch the access token                            | String    | Required                                                                                           | The ID should be a valid app Id of Gupshup.               |
| messaging\_product | whatsapp                  | Messaging product                                           | String    | Required                                                                                           |                                                           |
| recipient\_type    | individual                | Recipient type                                              | String    | Required                                                                                           |                                                           |
| to                 | 91785876xxxx              | Destination phone number where the message needs to be sent | String    | Required (Can be optional if BSUID is enabled for the app and recipient parameter is used instead) | Must be a valid phone number                              |
| recipient          | IN.461449821882xxxx       | Destination BSUID where the message needs to be sent        | String    | Optional                                                                                           | Must be a valid BSUID                                     |
| type               | template                  | Messaging type                                              | String    | Required                                                                                           | The type should be `template` to send a template message. |
| template           | `{<BODY>}`                | Template message inside body                                | Object    | Required                                                                                           |                                                           |

## Sample Request

```curl
curl --location 'https://partner.gupshup.io/partner/app/{{APP_ID}}/v3/message' \
--header 'accept: application/json' \
--header 'Authorization: {{PARTNER_APP_TOKEN}}' \
--header 'Content-Type: application/json' \
--data '{
	"messaging_product": "whatsapp",
	"recipient_type": "individual",
  "to": "PHONE_NUMBER",
	"recipient": "BSUID",
	"type": "template",
	"template": {
		"name": "TEMPLATE_NAME",
		"language": {
			"code": "LANGUAGE_AND_LOCALE_CODE"
		},
		"components": [
			{
				"type": "header",
				"parameters": [
				{
					"type": "image",
					"image": {
						"link": "https://URL"
					}
				}
			]
		},
		{
			"type": "body",
			"parameters": [
				{
					"type": "text",
					"text": "TEXT-STRING"
				},
				{
					"type": "currency",
					"currency": {
					"fallback_value": "VALUE",
					"code": "USD",
					"amount_1000": "NUMBER"
					}
				},
				{
					"type": "date_time",
					"date_time": {
					"fallback_value": "MONTH DAY, YEAR"
					}
				}
			]
		}
	]
}
```

## Sample Response

```json
{  
	"messages": [  
		{  
			"id": "GUPSHUP_MESSAGE_ID"  
		}  
	],  
	"messaging_product": "whatsapp",  
	"contacts": [  
		{  
			"input": "DESTINATION_PHONE_NO",  
			"wa_id": "DESTINATION_PHONE_NO"  
		}  
	]  
}
```

## Status Codes

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Status Code
      </th>

      <th>
        Response
      </th>

      <th>
        Comments
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        **Success**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        200
      </td>

      <td>
        ```
        {  
        	"messages": [  
        		{  
        			"id": "GUPSHUP_MESSAGE_ID"  
        		}  
        	],  
        	"messaging_product": "whatsapp",  
        	"contacts": [  
        		{  
        			"input": "DESTINATION_PHONE_NO",  
        			"wa_id": "DESTINATION_PHONE_NO"  
        		}  
        	]  
        }
        ```
      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        **Error**
      </td>

      <td>

      </td>

      <td>

      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        ```
        {  
        	"message": "Callback Billing must be enabled for this API",  
        	"status": "error"  
        }
        ```
      </td>

      <td>
        if Callback billing is not  
        enabled for the app
      </td>
    </tr>

    <tr>
      <td>
        400
      </td>

      <td>
        ```
        {  
        	"message": "Invalid App Details",  
        	"status": "error"  
        }
        ```
      </td>

      <td>
        if app details are not found
      </td>
    </tr>

    <tr>
      <td>
        401
      </td>

      <td>
        ```
        {  
        	"status": "error",  
        	"message": "Authentication Failed"  
        }
        ```
      </td>

      <td>
        When API key authentication fails
      </td>
    </tr>
  </tbody>
</Table>

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Partner Portal API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://partner.gupshup.io"
    }
  ],
  "paths": {
    "/partner/app/{appId}/v3/message": {
      "post": {
        "summary": "Media-Based Message Template",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "example": {
                  "messaging_product": "whatsapp",
                  "recipient_type": "individual",
                  "to": "PHONE_NUMBER",
                  "type": "template",
                  "template": {
                    "name": "TEMPLATE_NAME",
                    "language": {
                      "code": "LANGUAGE_AND_LOCALE_CODE"
                    },
                    "components": [
                      {
                        "type": "header",
                        "parameters": [
                          {
                            "type": "image",
                            "image": {
                              "link": "https://URL"
                            }
                          }
                        ]
                      },
                      {
                        "type": "body",
                        "parameters": [
                          {
                            "type": "text",
                            "text": "TEXT-STRING"
                          },
                          {
                            "type": "currency",
                            "currency": {
                              "fallback_value": "VALUE",
                              "code": "USD",
                              "amount_1000": "NUMBER"
                            }
                          },
                          {
                            "type": "date_time",
                            "date_time": {
                              "fallback_value": "MONTH DAY, YEAR"
                            }
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "Your app token, please refer [**Get access token api**](https://partner-docs.gupshup.io/reference/get_partner-app-appid-token) to get the token from partner documentation.",
            "example": "sk_61b3021c97214370b341f8baaae0xxxx",
            "required": true
          },
          {
            "name": "appId",
            "in": "path",
            "schema": {
              "type": "string"
            },
            "required": true,
            "description": "Unique identifier of the app.",
            "example": "9e97650d-xxxx-xxxx-xxxx-4cdf47c3fa68"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "messages": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "example": "GUPSHUP_MESSAGE_ID"
                          }
                        }
                      },
                      "example": [
                        {
                          "id": "GUPSHUP_MESSAGE_ID"
                        }
                      ]
                    },
                    "messaging_product": {
                      "type": "string",
                      "example": "whatsapp"
                    },
                    "contacts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "input": {
                            "type": "string",
                            "example": "DESTINATION_PHONE_NO"
                          },
                          "wa_id": {
                            "type": "string",
                            "example": "DESTINATION_PHONE_NO"
                          }
                        }
                      },
                      "example": [
                        {
                          "input": "DESTINATION_PHONE_NO",
                          "wa_id": "DESTINATION_PHONE_NO"
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Callback Billing must be enabled for this API"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Authentication Failed"
                    },
                    "status": {
                      "type": "string",
                      "example": "error"
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Use this API to send a media based  message as template."
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
```