Send channel messages API

curl -X POST \
  https://us.api.hellotars.com/api/channels/send \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "whatsapp",
    "to": "+15551234567",
    "type": "template",
    "convId": "YOUR_AGENT_ID",
    "template": {
      "name": "order_update",
      "language": "en_US",
      "parameters": { "body": ["A-1042", "shipped"] }
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/channels/send",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channel: "whatsapp",
      to: "+15551234567",
      type: "template",
      convId: "YOUR_AGENT_ID",
      template: {
        name: "order_update",
        language: "en_US",
        parameters: { body: ["A-1042", "shipped"] }
      }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/channels/send",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "to": "+15551234567",
        "type": "template",
        "convId": "YOUR_AGENT_ID",
        "template": {
            "name": "order_update",
            "language": "en_US",
            "parameters": {"body": ["A-1042", "shipped"]},
        },
    },
)

data = response.json()

{
  "success": true,
  "messageType": "template",
  "channel": "whatsapp",
  "messageId": "PROVIDER_MESSAGE_ID"
}

POST

api

channels

send

curl -X POST \
  https://us.api.hellotars.com/api/channels/send \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "whatsapp",
    "to": "+15551234567",
    "type": "template",
    "convId": "YOUR_AGENT_ID",
    "template": {
      "name": "order_update",
      "language": "en_US",
      "parameters": { "body": ["A-1042", "shipped"] }
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/channels/send",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channel: "whatsapp",
      to: "+15551234567",
      type: "template",
      convId: "YOUR_AGENT_ID",
      template: {
        name: "order_update",
        language: "en_US",
        parameters: { body: ["A-1042", "shipped"] }
      }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/channels/send",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "to": "+15551234567",
        "type": "template",
        "convId": "YOUR_AGENT_ID",
        "template": {
            "name": "order_update",
            "language": "en_US",
            "parameters": {"body": ["A-1042", "shipped"]},
        },
    },
)

data = response.json()

{
  "success": true,
  "messageType": "template",
  "channel": "whatsapp",
  "messageId": "PROVIDER_MESSAGE_ID"
}

The message goes out from the WhatsApp number assigned to the target agent, so that agent needs a connected number first. A plain message send works only inside an open messaging window. Use template for out-of-window messages.

A WhatsApp send branching on the messaging window, with a plain text message inside the window and an approved template outside it

Request

string

required

Bearer YOUR_API_KEY, a key with the Channels permission.

string

required

whatsapp. Any other value fails with a 400.

string

required

The recipient’s channel identifier. For WhatsApp, the phone number in international format.

string

required

template or message.

string

The target agent’s public ID. Required for organization keys. Agent-scoped keys default to their own agent.

object

The approved template to send. Required with type: "template".

Show template properties

string

required

The approved template’s name.

string

required

The template’s language code, for example en_US.

object

body and header arrays of strings, in positional order.

object

{ "text": "…" }, a plain text message. Required with type: "message".

curl -X POST \
  https://us.api.hellotars.com/api/channels/send \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channel": "whatsapp",
    "to": "+15551234567",
    "type": "template",
    "convId": "YOUR_AGENT_ID",
    "template": {
      "name": "order_update",
      "language": "en_US",
      "parameters": { "body": ["A-1042", "shipped"] }
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/channels/send",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channel: "whatsapp",
      to: "+15551234567",
      type: "template",
      convId: "YOUR_AGENT_ID",
      template: {
        name: "order_update",
        language: "en_US",
        parameters: { body: ["A-1042", "shipped"] }
      }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/channels/send",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channel": "whatsapp",
        "to": "+15551234567",
        "type": "template",
        "convId": "YOUR_AGENT_ID",
        "template": {
            "name": "order_update",
            "language": "en_US",
            "parameters": {"body": ["A-1042", "shipped"]},
        },
    },
)

data = response.json()

Response

boolean

true on a successful send.

string

template or message, echoing the send type.

string

The channel the message was sent on.

string

The provider’s message ID when the provider returns one.

{
  "success": true,
  "messageType": "template",
  "channel": "whatsapp",
  "messageId": "PROVIDER_MESSAGE_ID"
}

Errors

Error responses return { "success": false, "error": "…" } with one of these statuses.

Status	Cause
`400`	Missing or invalid body fields, no WhatsApp number assigned to the agent, or an organization key without `convId`
`400`	A `type` sent without its matching `template` or `message` object
`400`	The provider rejected the send
`401`	Missing `Authorization` header, or an invalid or revoked key
`403`	Key not authorized for this agent, or the key lacks the Channels permission
`404`	No agent in your organization matches `convId`
`429`	Rate limit exceeded. Retry after the `Retry-After: 60` header elapses

Authorizations

Authorization

string

header

required

API key sent as Authorization: Bearer YOUR_API_KEY. Campaign endpoints use campaign-scoped keys; the rest use organization or agent keys with the matching permission.

Body

application/json

channel

enum<string>

required

The channel to send on. Only whatsapp can deliver today, and every other value is rejected.

Available options:

whatsapp

string

required

The recipient's channel identifier. For WhatsApp, the phone number in international format.

type

enum<string>

required

Send an approved template, or a plain text message inside an open messaging window. Use template outside the window.

Available options:

template,

message

convId

string

Target agent's public ID. Required for organization keys, and defaulted for agent-scoped keys.

template

object

The approved template to send. Required when type is template.

Show child attributes

message

object

A plain text message. Required when type is message.

Show child attributes

Response

Message sent

success

boolean

required

True when the channel accepted the message.

messageType

enum<string>

Echoes the send type from the request.

Available options:

template,

message

channel

string

The channel the message went out on.

messageId

string

The provider's message ID, when the provider returned one. Use it to match delivery webhooks.

Welcome

Core concepts

Guides

Developer

Send channel messages API

Request

Response

Errors

Authorizations

Body

Response

​Request

​Response

​Errors

​Related pages

Authorizations

Body

Response

Request

Response

Errors

Related pages