Conversations API

Version: v2.16

Specification Release Notes Postman Collection Other versions

The Conversations API allows you to easily send messages to your customers via messaging services like WhatsApp or Viber and still reach customers with classic SMS, with a harmonized data model over all channels.

This API is designed for 2-way messaging (sending and receiving), which allows interactive conversations with your customers.

Delivery notifications (message status updates) and inbound messages from your customers are sent by us to your system via the HTTP POST method. For details see Receiving status updates and Receiving inbound messages.

Sunset note

This version of the API will be discontinued on 31.12.2022.

The last feature update will happen on 31.06.2022.

Please start your migration to Version 3.

Adhered web standards

In addition to the compliance common to all our APIs, the Conversations API complies also with:

RFC 5988 – Web Linking

RFC 5988 is implemented to allow all API calls that return a list of resources, to make use of the following Link headers:

first – The first page in the resource list pagination
previous – The preceding page of the current page in the resource list pagination
current – The current page in the resource list pagination
next – The following page in the current page of the resource list pagination
last – The last page in the resource list pagination

In addition, the following custom headers are provided for convenience:

x-total-pages – The total number of pages in the list of requested sub-resources
x-total-items – The total number of items in the list of requested sub-resources
x-page-size – The size of a page (maximum number of items on a single page)
x-current-page – The page number of the current page in the list of requested sub-resources

Channels

The Conversations API provides messaging services via several channels, currently:

WhatsApp
Viber
2-way SMS (sending and receiving)

Note: If you want to send SMS only, check out our SMS API, which is preferred for 1-way SMS messaging.

Channel specific prerequisites

WhatsApp: A WhatsApp Business Account (WABA) is required in order to use this channel.
Please request your access here.
Viber: A Viber Service ID is required in order to use this channel.
Please request your access here.
2-way SMS: Please contact us to get the details for the 2-way SMS setup.

Common Operations

Version: v2.12

Specification Release Notes Postman Collection Other versions

In this section, you find an overview of operations common to all Conversations channels.

The Conversations API works as a wrapper for messaging on varied channels and aims to provide a common data model unified to the greatest possible extent.

Here are some guidelines on the general usage. For details about interaction on a particular channel, please refer to the channel specific section.

Sending messages

All channels use the same endpoint and generic data model for requests to send messages. However, the components of messages beyond plain text are channel specific. Some channels enforce special policies and restrictions, for example the WhatsApp channel, and you need to watch that you comply with them in the context of your use case.

For details on the channels, please refer to the channel specific section.

Media and other non-text content

Some channels allow you to attach images, video, audio, stickers, buttons or URLs. These kinds of content are channel specific.

Bulk messaging

All channels provide the functionality of sending bulks of messages. A bulk of messages is always sent via one channel to a single recipient.

Our system guarantees that the messages are sent to the recipient in the requested order.

Receiving status updates

The API allows you to automatically receive delivery notifications and status updates about messages that you sent to your channels.

For this service, you will need to provide a URL (callbackUrl) at your webserver, e.g. https://rest.customer.com/messagestatus/. This URL must serve a webhook able to process POST HTTP requests, which the tyntec application will fire upon events in the system, in this case upon message status updates.

You will also need to subscribe your callback URL to one or more MessageStatus::* event types in the tyntec application, see Webhook Configuration and Webhook Events. The set of available event types slightly varies on each channel:

WhatsApp: Accepted, Delivered, Seen, Channel failed, Failed, Deleted
Viber: Accepted, Delivered, Seen, Channel failed, Failed
SMS: Accepted, Delivered, Channel failed, Failed

Retries

The tyntec application will retry to post the request 2 more times in the case your webhook does not accept the request (final response codes other than 2xx).

Receiving inbound messages

The API allows you to automatically receive inbound messages sent to your channels by your customers.

Note: For the SMS channel, you need to ask us to enable 2-way interaction, see Channel specific prerequisites.

For this service, you will need to provide a URL (callbackUrl) at your webserver, e.g. https://rest.customer.com/inboundmessages/. This URL must serve a webhook able to process POST HTTP requests, which the tyntec application will fire upon the events of inbound messages.

You will also need to subscribe your callback URL to the MoMessage event type in the tyntec application, see Webhook Configuration and Webhook Events.

Retries

The tyntec application will retry to post the request in the case your webhook does not accept the request (final response codes other than 2xx), depending on the channel as follows:

WhatsApp: retries via the WhatsApp mechanism with exponential decrease in frequency of attempts that continues up to 14 days (attempts repeat less and less often)
Viber: TODO
SMS: retries every 10 seconds. Retries are paused for 10 minutes after every 100 consecutive unsuccessful delivery attempts. tyntec's application will keep trying for a maximum of 48 hours.

Base URLs

https://api.tyntec.com/chat-api/v2

Message details

Operations on single sent messages common to all channels. They provide detailed information about sent messages.

Retrieve a sent message

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}

Returns a message previously sent by you.

Important

After a final status notification (delivered, read or failed), the message is only available for the next 48 hours. After this period, we delete the message from our system.

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The requested message ID exists.	StoredMessage
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Check message status

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id}/status \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id}/status HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}/status',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}/status',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}/status', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}/status', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}/status");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}/status", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}/status

Check status of the message

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "event": "MessageStatus::seen",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "status": "seen",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "from": 491672634678
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The requested message ID exists.	MessageStatus
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

View message history

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id}/history \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id}/history HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}/history',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}/history',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}/history', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}/history', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}/history");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}/history", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}/history

Returns the history of a sent message.

This will give you detailed information about the delivery flow of the message.

Recommended for debugging.

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "userContext": "my-message-reference",
  "history": [
    {
      "deliveryChannel": "whatsapp",
      "happenedAt": "2019-03-13T12:57:27.048Z",
      "state": "accepted"
    }
  ]
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The history of the message ID	MessageHistory
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Inbound media

After receiving an inbound message (MoMessage event) with a media ID, this endpoint can be used to download the media file.

Download inbound media

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/media/{media-id} \
  -H 'Accept: audio/*' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/media/{media-id} HTTP/1.1
Host: api.tyntec.com
Accept: audio/*
apikey: API_KEY


const headers = {
  'Accept':'audio/*',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/media/{media-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'audio/*',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/media/{media-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'audio/*',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/media/{media-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'audio/*',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/media/{media-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/media/{media-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "audio/*");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"audio/*"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/media/{media-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /media/{media-id}

Retrieve the media associated with a media ID.

Parameters

Name	In	Type	Required	Description
media-id	path	string(uuid)	true	The ID of the media to be downloaded

Example responses

200 Response

404 Response

{
  "status": 404
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParsable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
200	OK	The requested media associated with the ID exists. Returned.	string
404	Not Found	The requested media associated with the ID does not exist in our system.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Schemas

MessageRequest

{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

The message you would like to send

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient of the message. It can be one of: - phone number in the international format. It should follow the guidelines of E.164 but leading 00 is accepted as well. - group ID previously created via group management if the channel supports it
channels	[string]	true	none	Channels selected for delivery.
overrides	MessageRequestOverrides	false	none	Overrides of defaults for this message
context	MessageRequestContext	false	none	Contextual information for the message request

StoredMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient phone number in the international format. It should follow the guidelines of E.164 but leading 00 is accepted as well.
channels	[string]	true	none	Channels selected for delivery.

MessageResponse

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string(uuid)	true	none	Global Message ID reference
acceptedAt	string(date-time)	true	none	Point in time when the API confirms that the message request was accepted

APIEvent

{
  "event": "MessageStatus::accepted",
  "channel": "sms",
  "from": 491672634678,
  "timestamp": "2019-06-26T11:41:00"
}

Basic type for events produced such as MessageStatus, InboundMessage and GroupEvent

Properties

Name	Type	Required	Restrictions	Description
event	EventTypes	true	none	Determines which event type is emitted by the API
channel	string	false	none	Channel which triggered the event. Can be empty in case of an internal source
timestamp	string(date-time)	false	none	Point in time when the event happened
from	string	false	none	Who triggered this event. Usually the phone number or WhatsApp account ID

Enumerated values

Property	Value
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber

EventTypes

"MoMessage"

Determines which event type is emitted by the API

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Determines which event type is emitted by the API

Enumerated values

Property	Value
anonymous	MoMessage
anonymous	MoMessage::Postback
anonymous	MessageStatus::accepted
anonymous	MessageStatus::channelFailed
anonymous	MessageStatus::deleted
anonymous	MessageStatus::delivered
anonymous	MessageStatus::failed
anonymous	MessageStatus::seen
anonymous	MessageStatus::unknown

MessageStatus

{
  "event": "MessageStatus::seen",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "status": "seen",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "from": 491672634678
}

The current status of a message.

It is used for messages sent and received by you.

In the case you sent the message, the status will inform you about the delivery process.

In the case that you receive a message from a user, the user may decide to delete the message. Then and only then the deleted status is emitted.

Properties

Name	Type	Required	Restrictions	Description
event	string	true	none	Determines which event type is sent.
messageId	string	true	none	Global Message ID reference
channel	string	false	none	Channel which triggered the event. Can be empty in the case of an internal source
deliveryChannel	string	false	none	Channel which was used for delivery. Note This property will be replaced in the future by the channel property from the APIEvent
status	string	true	none	Indicates the status of the message. Be aware that not all channels support all statuses. Note This property will be replaced by the property event in a future release.
timestamp	string(date-time)	true	none	Point in time when the event happened
userContext	string	false	none	Contextual information set in the message request
from	string	false	none	Who triggered this event. Usually the phone number or WhatsApp account ID
details	HistoryDetails	false	none	Further information available for this event

Enumerated values

Property	Value
event	MessageStatus::accepted
event	MessageStatus::delivered
event	MessageStatus::seen
event	MessageStatus::failed
event	MessageStatus::unknown
channel	sms
channel	whatsapp
channel	tyntecEcho
deliveryChannel	sms
deliveryChannel	whatsapp
deliveryChannel	tyntecEcho
status	accepted
status	delivered
status	seen
status	failed
status	unknown

MessageHistory

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "userContext": "my-message-reference",
  "history": [
    {
      "deliveryChannel": "whatsapp",
      "happenedAt": "2019-03-13T12:57:27.048Z",
      "state": "accepted"
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string(uuid)	false	none	Global Message ID reference
userContext	string	false	none	Contextual information set in the message request
history	[HistoryItem]	false	none	Ordered list of current available events for your message

HistoryItem

{
  "deliveryChannel": "whatsapp",
  "happenedAt": "2019-03-13T13:15:22Z",
  "state": "accepted"
}

Contains information about a specific event occuring in the delivery process

Properties

Name	Type	Required	Restrictions	Description
deliveryChannel	string	false	none	The channel triggering this event
channel	string	false	none	The channel triggering this event
happenedAt	string(date-time)	false	none	When did the event happen
state	string	false	none	State of the message delivery
details	HistoryDetails	false	none	Further information available for this event

Enumerated values

Property	Value
deliveryChannel	sms
deliveryChannel	whatsapp
deliveryChannel	tyntecEcho
channel	sms
channel	whatsapp
channel	tyntecEcho
state	accepted
state	dispatched
state	dispatching_failed
state	success
state	failed
state	unknown

HistoryDetails

{
  "code": "tyntec::error:noFurtherChannelAvailable",
  "message": "No further channel after Channel[whatsapp] available",
  "from": 491672634678
}

Further information available for this event

Properties

Name	Type	Required	Restrictions	Description
code	string	false	none	Code specific to the details
message	string	false	none	Textual representation of the code, containing further information
from	string	false	none	Who triggered this event. Usually the phone number or WhatsApp account ID

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParsable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows the RFC 7807

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference RFC 3986 that identifies the problem type
title	string	true	none	A short, human-readable summary of the problem type.
status	string	true	none	The HTTP status code (RFC 7231, Section 6) generated by the origin server for this occurrence of the problem.
detail	string	true	none	A human-readable explanation specific to this occurrence of the problem.

MessageRequestContext

{
  "userContext": "my-message-reference"
}

Contextual information for the message request

Properties

Name	Type	Required	Restrictions	Description
userContext	string	false	none	Contextual information that is transfered back in delivery notifications.

MessageRequestOverrides

{
  "notificationCallbackUrl": "https://en4u5fpprib5i.x.pipedream.net"
}

Overrides of defaults for this message

Properties

Name	Type	Required	Restrictions	Description
notificationCallbackUrl	string	false	none	When present this url is used for sending the delivery notifications to your webhook. Can be used for debugging use cases or individual routings.

BulkRequest

{
  "to": "string",
  "from": "string",
  "channel": "sms"
}

Bulk request to be sent. The items are guaranted to be sent in order of appearance

Properties

Name	Type	Required	Restrictions	Description
to	string	false	none	none
from	string	false	none	none
channel	string	false	none	Channel which should be used for the bulk

Enumerated values

Property	Value
channel	sms
channel	whatsapp
channel	viber

BulkAcceptedResponse

{
  "bulkId": "77185196-664a-43ec-b14a-fe97036c697f",
  "messageIds": [
    "77185196-664a-43ec-b14a-fe97036c697f",
    "77185196-664a-43ec-b14a-fe97036c697f"
  ]
}

Properties

Name	Type	Required	Restrictions	Description
bulkId	string(uuid)	false	none	none
messageIds	[string]	false	none	none

Version: v2.17

Specification Release Notes Postman Collection Other versions

Conversations allows you to easily send messages to your customers via WhatsApp

Channel specific prerequisites

WhatsApp: A WhatsApp Business Account is required in order to use this channel. Please, request your access here.

Base URLs

https://api.tyntec.com/chat-api/v2

Messaging

In this section, we guide you on how to send messages, get information about the status and the events happening during delivery.

Send a message

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/messages HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "12331132",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "1233423454",
    "contentType": "text",
    "text": "hi!"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/messages',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/messages', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/messages', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/messages", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /messages

Send a WhatsApp message.

Body parameter

{
  "to": "12331132",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "1233423454",
    "contentType": "text",
    "text": "hi!"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	MessageRequest	true	The message you would like to send

Example responses

202 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The message was accepted by our system.	MessageResponse
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Retrieve the message

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}

Returns a message previously sent by you.

Important

After a final status notification (delivered, read or failed), the message is only available for the next 48 hours. After this period, we delete the message from our system.

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The message ID requested exists.	StoredMessage
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Send a bulk of messages

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/bulks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/bulks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "string",
  "from": "string",
  "channel": "whatsapp",
  "whatsapp": [
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    },
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/bulks',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/bulks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/bulks', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/bulks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/bulks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/bulks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /bulks

Send a bulk of messages via one channel to one recipient.

The system guarantees that the messages are sent in order to the recipient

Body parameter

{
  "to": "string",
  "from": "string",
  "channel": "whatsapp",
  "whatsapp": [
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    },
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	BulkRequest	true	The message bulk you want to send

Example responses

202 Response

{
  "bulkId": "77185196-664a-43ec-b14a-fe97036c697f",
  "messageIds": [
    "77185196-664a-43ec-b14a-fe97036c697f",
    "77185196-664a-43ec-b14a-fe97036c697f"
  ]
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The requested bulk was accepted	Inline
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Schema

Status Code 202

Name	Type	Required	Restrictions	Description
» bulkId	string(uuid)	false	none	none
» messageIds	[string]	false	none	none

Mark a message as read

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

const inputBody = '{
  "status": "read"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.put('https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/messages/{message-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /channels/whatsapp/messages/{message-id}

Marks a previously received WhatsApp message as read

Body parameter

{
  "status": "read"
}

Parameters

Name	In	Type	Required	Description
body	body	WhatsAppMessageStatusUpdate	true	The status change to execute
message-id	path	string	true	The ID of the MoMessage

Example responses

404 Response

{
  "status": 404,
  "title": "Not Found"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
200	OK	Message was successfully marked as read.	None
404	Not Found	No MoMessage found for the given Message ID.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Account management

Account management grants you access to information about the WhatsApp accounts provisioned to you.

At the moment, it does not support requesting new WhatsApp accounts or editing existing ones.

The WhatsApp account and its subresources can only be managed by one of your CPaaS API Accounts.

Read access to an account is available for all accounts that are associated with a phone number and thus eligible for sending messages.

List accounts

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts

Lists all WhatsApp accounts managed by these access credentials.

If the phone number query parameter is set, only the phone numbers account is listed.

Parameters

Name	In	Type	Required	Description
phone-number	query	integer	false	Phone number used for WhatsApp messaging.

Example responses

200 Response

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "whatsAppAccountName": "Swagger Sample Account",
    "businessName": "Swagger Sample business",
    "templateNamespace": "c9468969-a3a3-4c17-95f7-1e8b2902ed74",
    "facebookBusinessManagerId": 1791147717848878,
    "accountStatus": {
      "messageOnBehalf": "PENDING"
    },
    "managedBy": {
      "accountName": "tynteccpaas"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Returned a list of WhatsApp accounts	WhatsAppAccounts
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Description
200	x-total-pages	integer	How many pages are available
200	x-total-items	integer	How many items are available in total
200	x-page-size	integer	Maximum number of items per page
200	x-current-page	integer	The current page
200	Link	undefined	Links describing pagination

Read an account

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts/{whatsapp-account-id}

Returns details of a WhatsApp account.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID

Example responses

200 Response

{
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "whatsAppAccountName": "Swagger Sample Account",
  "businessName": "Swagger Sample business",
  "templateNamespace": "c9468969-a3a3-4c17-95f7-1e8b2902ed74",
  "facebookBusinessManagerId": 1791147717848878,
  "accountStatus": {
    "messageOnBehalf": "PENDING"
  },
  "managedBy": {
    "accountName": "tynteccpaas"
  }
}

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned a WhatsApp account	WhatsAppAccount
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

List phone numbers

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts/{whatsapp-account-id}/phone-numbers

Lists all phone numbers of a WhatsApp account.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID

Example responses

200 Response

[
  {
    "phoneNumber": 4912345678,
    "displayPhonenumber": "+49 123 45678",
    "verifiedName": "Swagger Sample",
    "qualityRating": "YELLOW",
    "status": "FLAGGED",
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "managedBy": {
      "accountName": "tyntecscpaas"
    },
    "messagingVia": {
      "accountName": "messagingcpaas"
    }
  }
]

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned phone numbers of a WhatsApp account	WhatsAppPhoneNumbers
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Description
200	x-total-pages	integer	How many pages are available
200	x-total-items	integer	How many items are available in total
200	x-page-size	integer	Maximum number of items per page
200	x-current-page	integer	The current page
200	Link	undefined	Links describing pagination

Template management

Template management enables you to interact with the templates defined for your WhatsApp account.

We support creating or deleting templates and adding new localizations to an existing template.

Due to restrictions by WhatsApp, editing is not supported yet.

List templates

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts/{whatsapp-account-id}/templates

Lists all templates of your WhatsApp account.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID

Example responses

200 Response

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "name": "swagger_test",
    "category": "TICKET_UPDATE",
    "localizations": [
      {
        "status": "REJECTED",
        "rejectionReason": "For this example",
        "language": "en",
        "components": [
          {
            "type": "BODY",
            "text": "Hello {{1}}! How is going?"
          },
          {
            "type": "FOOTER",
            "text": "Your specification team!"
          }
        ]
      }
    ]
  }
]

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned the templates	WhatsAppTemplates
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Description
200	x-total-pages	integer	How many pages are available
200	x-total-items	integer	How many items are available in total
200	x-page-size	integer	Maximum number of items per page
200	x-current-page	integer	The current page
200	Link	undefined	Links describing pagination

Submit a template for review

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

const inputBody = '{
  "name": "welcome",
  "category": "AUTO_REPLY",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}},\n\nwelcome at our support.\nHow can we help you?\n\nYour support team\n"
        }
      ]
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /channels/whatsapp/accounts/{whatsapp-account-id}/templates

Creates a new template that is submitted for review to Facebook.

Body parameter

{
  "name": "welcome",
  "category": "AUTO_REPLY",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}},\n\nwelcome at our support.\nHow can we help you?\n\nYour support team\n"
        }
      ]
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	WhatsAppTemplateRequest	true	The template to be submitted
whatsapp-account-id	path	string	true	WhatsApp account ID

Detailed description

body: The template to be submitted

Example responses

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
201	Created	The requested resource was created.	None
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Format	Description
201	Location	string		Location URI of the newly created resource

Read a template

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}

Returns details of a template in your WhatsApp account.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID
template-id	path	string	true	Referenced template

Example responses

200 Response

{
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "name": "swagger_test",
  "category": "TICKET_UPDATE",
  "localizations": [
    {
      "status": "REJECTED",
      "rejectionReason": "For this example",
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}! How is going?"
        },
        {
          "type": "FOOTER",
          "text": "Your specification team!"
        }
      ]
    }
  ]
}

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned the template from your account	WhatsAppTemplateResponse
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Delete a template

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id} \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

DELETE https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/problem+json
apikey: API_KEY


const headers = {
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.delete 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.delete('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('DELETE','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

DELETE /channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}

Deletes the template from your WhatsApp account.

After deleting the template, a 30-days grace period is starting. This is indicated by the expiresAt property of the localizations.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID
template-id	path	string	true	Referenced template

Example responses

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Deletion of the template is pending now.	None
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

List localizations

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations

Lists localizations of a template.

Parameters

Name	In	Type	Required	Description
whatsapp-account-id	path	string	true	WhatsApp account ID
template-id	path	string	true	Referenced template

Example responses

200 Response

[
  {
    "status": "DELETED",
    "rejectionReason": "not yet",
    "language": "en",
    "components": [
      {
        "type": "BODY",
        "text": "Hello {{1}}! How is going?"
      }
    ],
    "createdAt": "2020-02-15T23:28:34.442Z",
    "lastUpdated": "2020-02-15T25:28:34.442Z",
    "expiresAt": "2020-03-15T23:28:34.442Z",
    "qualityScore": {
      "score": "RED",
      "reasons": [
        "Users are choosing \"didn't sign up\" as a reason for blocking this phone number. Businesses must obtain opt-in before sending notifications. Please review your opt-in flow(s) and see our Business Policy for more detail."
      ]
    }
  }
]

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned localizations of the template.	Inline
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
anonymous	[LocalizationResponse]	false	none	[Localization of a template]
» status	string	true	none	Status the localization.
» rejectionReason	string	false	none	Descriptive text in the case the status is REJECTED
» language	LanguageCode	true	none	Supported language codes, according to Supported Languages
» components	[anyOf]	true	none	Set of components defining a template

anyOf

Name	Type	Required	Restrictions	Description
»» anonymous	WhatsAppTemplateHeaderComponentResponse	false	none	Header component of a template
»»» type	string	true	none	Component type
»»» format	string	true	none	Which kind of header
»»» text	string	false	none	Text based part of format "TEXT

Name	Type	Required	Restrictions	Description
»» anonymous	WhatsAppTemplateBodyComponentResponse	false	none	Body component of a template
»»» type	string	true	none	Component type
»»» text	string	true	none	Specification of the body text

Name	Type	Required	Restrictions	Description
»» anonymous	WhatsAppTemplateFooterComponentResponse	false	none	Footer component of a template
»»» type	string	true	none	Component type
»»» text	string	true	none	Specification of the footer text

continued

Name	Type	Required	Restrictions	Description
» createdAt	string(date-time)	true	none	At which point in time the template was created
» lastUpdated	string(date-time)	true	none	At which point in time the last update happened
» expiresAt	string(date-time)	false	none	When does the localization expire. Only present when a template was deleted.
» qualityScore	QualityScore	false	none	The quality score provided by WhatsApp and calculated from user feedback on your messages
»» score	string	true	none	The current scoring
»» reasons	[string]	false	none	Textual description why the quality score is set to the value. Only present when score is YELLOW or RED

Enumerated values

Property	Value
status	REQUESTED
status	SUBMIT_FAILED
status	PENDING
status	APPROVED
status	REJECTED
status	DELETION_PENDING
status	DELETED
status	SUBMITTED
language	af
language	ar
language	az
language	bg
language	bn
language	ca
language	cs
language	da
language	de
language	el
language	en
language	en_GB
language	en_US
language	es
language	es_AR
language	es_ES
language	es_MX
language	et
language	fa
language	fi
language	fil
language	fr
language	ga
language	gu
language	ha
language	he
language	hi
language	hr
language	hu
language	ID
language	it
language	ja
language	kk
language	kn
language	ko
language	lo
language	lt
language	lv
language	mk
language	ml
language	mr
language	ms
language	nb
language	nl
language	pa
language	pl
language	pt_BR
language	pt_PT
language	ro
language	ru
language	sk
language	sl
language	sq
language	sr
language	sv
language	sw
language	ta
language	te
language	th
language	tr
language	uk
language	ur
language	uz
language	vi
language	zh_CN
language	zh_HK
language	zh_TW
language	zu
type	HEADER
format	IMAGE
format	TEXT
format	DOCUMENT
format	VIDEO
type	BODY
type	FOOTER
score	unknown
score	GREEN
score	YELLOW
score	RED

Add a localization

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

const inputBody = '{
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/localizations

Adds a localization to a template. The localization will be separately reviewed by Facebook.

Body parameter

{
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "string"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	LocalizationRequest	true	The localization to be submitted
whatsapp-account-id	path	string	true	WhatsApp account ID
template-id	path	string	true	Referenced template

Detailed description

body: The localization to be submitted

Example responses

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

404 Response

{
  "status": 404,
  "title": "WhatsApp account unknown"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
201	Created	The requested resource was created.	None
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
404	Not Found	The WhatsApp account does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Format	Description
201	Location	string		Location URI of the newly created resource

Phone Number insights

Phone Number insights allow you to get information about the status of a phone number in your account.

It also provides read access to the templates usable with the phone number.

List phone numbers

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/phone-numbers

Lists all phone numbers accessible for the given credentials.

Example responses

200 Response

[
  {
    "phoneNumber": 4912345678,
    "displayPhonenumber": "+49 123 45678",
    "verifiedName": "Swagger Sample",
    "qualityRating": "YELLOW",
    "status": "FLAGGED",
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "managedBy": {
      "accountName": "tyntecscpaas"
    },
    "messagingVia": {
      "accountName": "messagingcpaas"
    }
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	Phone numbers assigned to your account	WhatsAppPhoneNumbers
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Description
200	x-total-pages	integer	How many pages are available
200	x-total-items	integer	How many items are available in total
200	x-page-size	integer	Maximum number of items per page
200	x-current-page	integer	The current page
200	Link	undefined	Links describing pagination

Read a phone number

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/phone-numbers/{phone-number}

Returns details about a phone number.

Parameters

Name	In	Type	Required	Description
phone-number	path	integer	true	Phone number used for WhatsApp messaging.

Example responses

200 Response

{
  "phoneNumber": 4912345678,
  "displayPhonenumber": "+49 123 45678",
  "verifiedName": "Swagger Sample",
  "qualityRating": "YELLOW",
  "status": "FLAGGED",
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "managedBy": {
    "accountName": "tyntecscpaas"
  },
  "messagingVia": {
    "accountName": "messagingcpaas"
  }
}

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned the details about the phone number	WhatsAppPhoneNumber
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

List available templates

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/templates", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/phone-numbers/{phone-number}/templates

Lists all available templates for a phone number

Parameters

Name	In	Type	Required	Description
phone-number	path	integer	true	Phone number used for WhatsApp messaging.

Example responses

200 Response

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "name": "swagger_test",
    "category": "TICKET_UPDATE",
    "localizations": [
      {
        "status": "REJECTED",
        "rejectionReason": "For this example",
        "language": "en",
        "components": [
          {
            "type": "BODY",
            "text": "Hello {{1}}! How is going?"
          },
          {
            "type": "FOOTER",
            "text": "Your specification team!"
          }
        ]
      }
    ]
  }
]

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned templates available for the phone number	WhatsAppTemplates
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Headers

Status	Header	Type	Description
200	x-total-pages	integer	How many pages are available
200	x-total-items	integer	How many items are available in total
200	x-page-size	integer	Maximum number of items per page
200	x-current-page	integer	The current page
200	Link	undefined	Links describing pagination

Profile management

Profile management allows you to read and update profile settings of your WhatsApp phone numbers.

Read the profile

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/phone-numbers/{phone-number}/settings/profile

Returns profile settings of a WhatsApp phone number

Parameters

Name	In	Type	Required	Description
phone-number	path	integer	true	Phone number used for WhatsApp messaging.

Example responses

200 Response

{
  "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
  "description": "tyntec WhatsApp Business API Demo",
  "email": "support@tyntec.com",
  "websites": [
    "https://www.tyntec.com",
    "https://api.tyntec.com/reference"
  ],
  "vertical": "Professional Services",
  "about": "Hey there! I am using WhatsApp."
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned the current profile settings	WhatsAppProfile
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Update the profile

Code samples

# You can also use wget
curl -X PATCH https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

PATCH https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

const inputBody = '{
  "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
  "description": "tyntec WhatsApp Business API Demo",
  "email": "support@tyntec.com",
  "websites": [
    "https://www.tyntec.com",
    "https://api.tyntec.com/reference"
  ],
  "vertical": "Professional Services",
  "about": "Hey there! I am using WhatsApp."
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.patch 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.patch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PATCH','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/profile", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PATCH /channels/whatsapp/phone-numbers/{phone-number}/settings/profile

Updates the WhatsApp client profile.

Supports also selective updates.

To remove a particular field, set its value to an empty string.

Body parameter

{
  "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
  "description": "tyntec WhatsApp Business API Demo",
  "email": "support@tyntec.com",
  "websites": [
    "https://www.tyntec.com",
    "https://api.tyntec.com/reference"
  ],
  "vertical": "Professional Services",
  "about": "Hey there! I am using WhatsApp."
}

Parameters

Name	In	Type	Required	Description
body	body	WhatsAppProfile	true	Information in order to create the group
phone-number	path	integer	true	Phone number used for WhatsApp messaging.

Example responses

400 Response

{
  "status": 400,
  "title": "Profile update failed.",
  "code": 1009
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Profile updated	None
400	Bad Request	Profile update failed. In the case a partial update failed: retrieve the current profile, change the required information and retry with the whole profile.	Inline
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Response Schema

Status Code 400

Name	Type	Required	Restrictions	Description
» code	string	false	none	error code

Read the logo

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo \
  -H 'Accept: image/png' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo HTTP/1.1
Host: api.tyntec.com
Accept: image/png
apikey: API_KEY


const headers = {
  'Accept':'image/png',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'image/png',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'image/png',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'image/png',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "image/png");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"image/png"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /channels/whatsapp/phone-numbers/{phone-number}/settings/logo

Returns the current logo assigned to a WhatsApp phone number profile.

Parameters

Name	In	Type	Required	Description
phone-number	path	integer	true	Phone number used for WhatsApp messaging.
format	query	string	false	The format in which the icon should be returned

Enumerated values

Parameter	Value
format	link
format	binary

Example responses

200 Response

{
  "link": "https://pps.whatsapp.net/v/123123"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

Responses

Status	Meaning	Description	Schema
200	OK	Returned the current logo	WhatsAppProfileLogoLink
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Update the logo

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo \
  -H 'Content-Type: image/png' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo HTTP/1.1
Host: api.tyntec.com
Content-Type: image/png
Accept: application/problem+json
apikey: API_KEY

const inputBody = 'string';
const headers = {
  'Content-Type':'image/png',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo',
{
  method: 'PUT',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'image/png',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'image/png',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.put('https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'image/png',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PUT','https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
con.setRequestProperty("Content-Type", "image/png");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"image/png"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PUT", "https://api.tyntec.com/chat-api/v2/channels/whatsapp/phone-numbers/{phone-number}/settings/logo", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PUT /channels/whatsapp/phone-numbers/{phone-number}/settings/logo

Updates the logo assigned to a WhatsApp phone number profile.

The logo must have a minimal edge size of 500 pixels and must not exceed 5 MB in size.

The recommended size is 640x640 pixels.

Body parameter

Parameters

Name	In	Type	Required	Description
body	body	string(binary)	true	Image that should be used as the profile logo
phone-number	path	integer	true	Phone number used for WhatsApp messaging.
format	query	string	false	The format in which the icon should be returned

Enumerated values

Parameter	Value
format	link
format	binary

Example responses

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

404 Response

{
  "status": 404,
  "title": "Phone number unknown"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Updated the logo successfully	None
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
403	Forbidden	You're attempting to use a number that is not assigned to your account.	Problem
404	Not Found	The phone number does not exist.	Problem
default	Default	Default response in case of any other error. Check the Problem object for details.	Problem

Schemas

MessageRequest

{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

The message you would like to send

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient of the message. Could be one of - phone number in the international format. It should follow the guidelines of E.164 but leading 00 is accepted as well. - group ID create via the WA Group management
channels	[string]	true	none	Channels selected for delivery.
overrides	MessageRequestOverrides	false	none	Overrides of defaults for this message
context	MessageRequestContext	false	none	Contextual information for the message request
whatsapp	WhatsappMessageRequest	false	none	Whatsapp message to be sent. This will override the defaults from DefaultContent.

StoredMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient phone number in the international format. It should follow the guidelines of E.164 but leading 00 is accepted as well.
channels	[string]	true	none	Channels selected for delivery.
whatsapp	WhatsappMessageRequest	false	none	Whatsapp message to be sent. This will override the defaults from DefaultContent.

WhatsappMessageRequest

{
  "from": "1233423454",
  "contentType": "media",
  "media": {
    "type": "audio",
    "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.svg",
    "caption": "Tyntec Logo"
  }
}

Whatsapp message to be sent.

This will override the defaults from DefaultContent.

Properties

Name	Type	Required	Restrictions	Description
from	string	true	none	The phone number of the sending WhatsApp account
contentType	string	true	none	What kind of payload is used
text	string	false	none	The text to be sent
url	string	false	none	The URL you would like to send. Must be a valid HTTP(S) URL. Note: This property will be removed in a future release. Please, switch to `text` with `urlPreviewDisplayed` set to `true`.
media	Media	false	none	Media file to be sent
template	Template	false	none	The message template to be sent.
location	Location	false	none	Location received or sent
urlPreviewDisplayed	boolean	false	none	Should a preview of the URL be rendered. This will only have an effect on text messages.
contacts	[Contact]	false	none	[Contact object]
interactive	any	false	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppInteractiveButtonMessage	false	none	Interactive message type

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppInteractiveListMessage	false	none	Interactive message type

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppInteractiveProductMessage	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppInteractiveProductListMessage	false	none	none

Enumerated values

Property	Value
contentType	template
contentType	text
contentType	url
contentType	media
contentType	location
contentType	contacts
contentType	interactive

Media

{
  "type": "audio",
  "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
}

Media file to be sent

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	AudioMedia	false	none	Audio file to be sent

xor

Name	Type	Required	Restrictions	Description
anonymous	ImageMedia	false	none	Image to be sent

xor

Name	Type	Required	Restrictions	Description
anonymous	DocumentMedia	false	none	Document to be sent

xor

Name	Type	Required	Restrictions	Description
anonymous	VideoMedia	false	none	Video file to be sent

xor

Name	Type	Required	Restrictions	Description
anonymous	StickerMedia	false	none	Sticker to be sent

AudioMedia

{
  "type": "audio",
  "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
}

Audio file to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	What kind of media should be sent
url	string	true	none	The URL of the location where the audio file is stored

Enumerated values

Property	Value
type	audio

ImageMedia

{
  "type": "image",
  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
}

Image to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	What kind of media should be sent. Can only be png or jpeg
url	string	true	none	The URL of the location where the image is stored
caption	string	false	none	An additional caption for the image. It is shown on the uploaded image when the channel supports this

Enumerated values

Property	Value
type	image

StickerMedia

{
  "type": "sticker",
  "url": "https://www.tyntec.com/sites/default/files/2020-07/tyntec_rocket_sticker_512px_001_.webp"
}

Sticker to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	What kind of media should be sent. It can only be a website
url	string	true	none	The URL of the location where the sticker is stored

Enumerated values

Property	Value
type	sticker

DocumentMedia

{
  "type": "document",
  "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
  "caption": "Tyntec Pricelist",
  "filename": "tyntec_pricelist.pdf"
}

Document to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	What kind of media should be sent
url	string	true	none	The URL of the location where the document is stored
caption	string	false	none	An additional caption for the document. It is shown on the uploaded document when the channel supports this
filename	string	false	none	File name of the document to be shown. It is shown on the uploaded document when the channel supports this

Enumerated values

Property	Value
type	document

VideoMedia

{
  "type": "video",
  "url": "http://techslides.com/demos/sample-videos/small.mp4",
  "caption": "Tyntec Party"
}

Video file to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	What kind of media should be sent
url	string	true	none	The URL of the location where the video is stored
caption	string	false	none	An additional caption for the video. It is shown on the uploaded video when the channel supports this

Enumerated values

Property	Value
type	video

Template

{
  "templateId": "weclome_message",
  "language": {
    "policy": "deterministic",
    "code": "en"
  },
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "media",
          "media": {
            "type": "image",
            "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Hi!"
        }
      ]
    }
  ]
}

The message template to be sent.

Properties

Name	Type	Required	Restrictions	Description
templateId	string	true	none	The identifier of the template that should be used
language	Language	true	none	Language settings for the template.
components	[anyOf]	false	none	Parameter for replacement in the template. Header and body components can only be used once. The button components can be used up to 3 times (quick replies) or 1 time (URL)

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	HeaderComponent	false	none	Header component.

Name	Type	Required	Restrictions	Description
» anonymous	BodyComponent	false	none	Body component.

Name	Type	Required	Restrictions	Description
» anonymous	QuickReplyButtonComponent	false	none	This type can be used up to three times.

Name	Type	Required	Restrictions	Description
» anonymous	UrlButtonComponent	false	none	This type can be used up to one time.

continued

Name	Type	Required	Restrictions	Description
parameters	[TemplateParameter]	false	none	Parameter for replacement in the template. Note: This parameter is deprecated by version 2.7 and will be removed in the next major release. Instead, use components.

Language

{
  "policy": "deterministic",
  "code": "en"
}

Language settings for the template.

Properties

Name	Type	Required	Restrictions	Description
policy	string	false	none	Used for multi-language template resolution. Note: We got notified by WhatsApp that they will drop the fallback policy on template messages. As we need to stay up-to-date with the WhatsApp API, we will also drop this policy in the next month. Please, switch to the language policy deterministic.
code	string	false	none	The code of the language or locale to use. Accepts both language and language_locale formats (e.g. en and en_US).

Enumerated values

Property	Value
policy	fallback
policy	deterministic

TemplateParameter

{
  "default": "Mr. Doe"
}

Parameter for replacement in the template.

The value can contain any character except:

newline
tabulator
more then 4 consecutive spaces.

It can be formatted according to How to format your messages.

NOTE: This parameter is deprecated by version 2.7 and will be removed in the next major release. Instead, use components.

Properties

Name	Type	Required	Restrictions	Description
default	string	false	none	Variable substitution.

HeaderComponent

{
  "type": "header",
  "parameters": [
    {
      "type": "media",
      "media": {
        "type": "image",
        "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
      }
    }
  ]
}

Header component.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the component. Always header.
parameters	[oneOf]	false	none	Parameters to be used in Header

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	TemplateMediaParameter	false	none	Media to be sent

xor

Name	Type	Required	Restrictions	Description
» anonymous	TextParameter	false	none	Text to be sent

xor

Name	Type	Required	Restrictions	Description
» anonymous	LocationParameter	false	none	Location to be sent.

Enumerated values

Property	Value
type	header

BodyComponent

{
  "type": "body",
  "parameters": [
    {
      "type": "text",
      "text": "Sam"
    },
    {
      "type": "text",
      "text": "nice replacement"
    }
  ]
}

Body component.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the component. Always body.
parameters	[anyOf]	false	none	Parameters to be used in the Body

Enumerated values

Property	Value
type	body

QuickReplyButtonComponent

{
  "type": "button",
  "subType": "quick_reply",
  "index": 0,
  "parameters": [
    {
      "type": "payload",
      "payload": "string"
    }
  ]
}

This type can be used up to three times.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the component. Always button.
subType	string	false	none	Determines the sub type of the button. Always quick_reply.
index	number	false	none	Determines the index of the button that should be enhanced with the payload.
parameters	[any]	false	none	Parameters for this quick reply button.
» type	string	false	none	Determines the type of the parameter. Always payload.
» payload	string	false	none	Payload for this quick reply button that is sent back on the `MoMessage::PostBack` event.

Enumerated values

Property	Value
type	button
subType	quick_reply
type	payload

UrlButtonComponent

{
  "type": "button",
  "subType": "url",
  "index": 0,
  "parameters": [
    {
      "type": "text",
      "text": "string"
    }
  ]
}

This type can be used up to one time.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the component. Always button.
subType	string	false	none	Determines the type of the component. Always url.
index	number	false	none	Determines the index of the button that should be enhanced with a custom parameter
parameters	[any]	false	none	Parameters to be used in Button's URL
» type	string	false	none	Determines the type of the parameter. Always text.
» text	string	false	none	Which text should be appended to a dynamic URL. Note: The requested template for a Button URL must end with {{1}}.

Enumerated values

Property	Value
type	button
subType	url
type	text

TextParameter

{
  "type": "text",
  "text": "Hi! Cool replacement"
}

Text to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the component. Always text.
text	string	false	none	Text for replacement in the template. The value can contain any character except: - newline - tabulator - more then 4 consecutive spaces. It can be formatted according to How to format your messages.

Enumerated values

Property	Value
type	text

LocationParameter

{
  "type": "location",
  "location": {
    "longitude": 7.4954884,
    "latitude": 51.5005765
  }
}

Location to be sent.

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the parameter. Always location.
location	TemplateHeaderLocation	false	none	Location used in template headers.

Enumerated values

Property	Value
type	location

TemplateHeaderLocation

{
  "longitude": 7.4954884,
  "latitude": 51.5005765
}

Location used in template headers.

Properties

Name	Type	Required	Restrictions	Description
longitude	number(double)	true	none	Longitude part of the coordinate
latitude	number(double)	true	none	Latitude part of the coordinate

TemplateMediaParameter

{
  "type": "media",
  "media": {
    "type": "image",
    "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png",
    "caption": "Tyntec Logo"
  }
}

Media to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the parameter. Always media.
media	any	false	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	ImageMedia	false	none	Image to be sent

xor

Name	Type	Required	Restrictions	Description
» anonymous	TemplateDocumentMedia	false	none	Media to be sent

xor

Name	Type	Required	Restrictions	Description
» anonymous	TemplateVideoMedia	false	none	Media to be sent

Enumerated values

Property	Value
type	media

TemplateDocumentMedia

{
  "type": "document",
  "url": "https://s1.q4cdn.com/806093406/files/doc_downloads/test.pdf",
  "filename": "Test document"
}

Media to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the media. Always document.
url	string	false	none	The URL of the location where the media is stored.
filename	string	false	none	Additional info for the filename to be displayed.

Enumerated values

Property	Value
type	document

TemplateVideoMedia

{
  "type": "video",
  "url": "http://techslides.com/demos/sample-videos/small.mp4"
}

Media to be sent

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Determines the type of the media. Always video.
url	string	false	none	The URL of the location where the media is stored.

Enumerated values

Property	Value
type	video

Location

{
  "longitude": 7.4954884,
  "latitude": 51.5005765,
  "name": "tyntec GmbH",
  "address": "tyntec GmbH, Semerteichstraße, Dortmund"
}

Location received or sent

Properties

Name	Type	Required	Restrictions	Description
longitude	number(double)	true	none	Longitude part of the coordinate
latitude	number(double)	true	none	Latitude part of the coordinate
name	string	false	none	Optional name
address	string	false	none	Optional address, will only be rendered if the name is set

Contact

{
  "birthday": "2018-01-01",
  "addresses": [
    {
      "city": "Dortmund",
      "country": "Germany",
      "countryCode": "de",
      "state": "NRW",
      "street": "string",
      "type": "WORK",
      "zip": 44231
    }
  ],
  "emails": [
    {
      "email": "whatsapp@tyntec.com",
      "type": "WORK"
    }
  ],
  "ims": [
    {
      "service": "WhatsApp",
      "userId": 123123123
    }
  ],
  "name": {
    "prefix": "Mr.",
    "firstName": "Peter",
    "middleName": "Michael",
    "lastName": "Tyntec",
    "suffix": "senior",
    "formattedName": "Mr. Peter Michael Tyntec senior"
  },
  "org": {
    "company": "tyntec GmbH",
    "department": "Development",
    "title": "API Guardian"
  },
  "phones": [
    {
      "phone": "+49 231 477 90 813",
      "type": "WORK"
    }
  ],
  "urls": [
    {
      "url": "https://www.tyntec.com",
      "type": "WORK"
    }
  ]
}

Contact object

Properties

Name	Type	Required	Restrictions	Description
birthday	string	false	none	Birthday of the contact
addresses	[Address]	false	none	List of addresses assigned to the contact
emails	[Email]	false	none	List of emails assigned to the contact
ims	[IMS]	false	none	List of IMS accounts assigned to the contact
name	Name	false	none	The name of a contact. In addition to the property `formattedName`, at least one of the other properties must be set.
org	Organisation	false	none	Organisation associated with the contact
phones	[ContactPhone]	false	none	List of phone numbers assigned to the contact
urls	[ContactUrl]	false	none	List of URLs assigned to the contact

Address

{
  "city": "Dortmund",
  "country": "Germany",
  "countryCode": "de",
  "state": "NRW",
  "street": "string",
  "type": "WORK",
  "zip": 44231
}

Address of a contact

Properties

Name	Type	Required	Restrictions	Description
city	string	false	none	City name
country	string	false	none	Full country name
countryCode	string	false	none	Two-letter country abbreviation
state	string	false	none	State abbreviation
street	string	false	none	Street name and number
type	string	false	none	Type of the address
zip	string	false	none	ZIP or postal code

Email

{
  "email": "whatsapp@tyntec.com",
  "type": "WORK"
}

Email of the contact

Properties

Name	Type	Required	Restrictions	Description
email	string	false	none	Email address
type	string	false	none	Type of the email

IMS

{
  "service": "WhatsApp",
  "userId": 123123123
}

IMS of the contact

Properties

Name	Type	Required	Restrictions	Description
service	string	false	none	Type of the email
userId	string	false	none	IMS user ID

Name

{
  "prefix": "Mr.",
  "firstName": "Peter",
  "middleName": "Michael",
  "lastName": "Tyntec",
  "suffix": "senior",
  "formattedName": "Mr. Peter Michael Tyntec senior"
}

The name of a contact. In addition to the property formattedName, at least one of the other properties must be set.

Properties

Name	Type	Required	Restrictions	Description
prefix	string	false	none	Prefix of the contacts name
firstName	string	false	none	First name of the contact
middleName	string	false	none	Middle name of the contact
lastName	string	false	none	Last name of the contact
suffix	string	false	none	Suffix of the contacts name
formattedName	string	true	none	Completely formatted name

Organisation

{
  "company": "tyntec GmbH",
  "department": "Development",
  "title": "API Guardian"
}

Organisation associated with the contact

Properties

Name	Type	Required	Restrictions	Description
company	string	false	none	Name of the contact's company
department	string	false	none	Name of the contact's department
title	string	false	none	Contact's business title

ContactPhone

{
  "phone": "+49 231 477 90 813",
  "type": "WORK"
}

Phone entry of a contact

Properties

Name	Type	Required	Restrictions	Description
phone	string	false	none	Phone number
type	string	false	none	Type of phone number

ContactUrl

{
  "url": "https://www.tyntec.com",
  "type": "WORK"
}

URL of a contact

Properties

Name	Type	Required	Restrictions	Description
url	string	false	none	URL of a contact
type	string	false	none	Type of URL

MessageResponse

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string(uuid)	true	none	Global Message ID reference
acceptedAt	string(date-time)	true	none	Point in time when the API confirms that the message request was accepted

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows the RFC 7807.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference RFC 3986 that identifies the problem type
title	string	true	none	A short, human-readable summary of the problem type.
status	string	true	none	The HTTP status code (RFC 7231, Section 6) generated by the origin server for this occurrence of the problem.
detail	string	true	none	A human-readable explanation specific to this occurrence of the problem.

MessageRequestContext

{
  "userContext": "my-message-reference"
}

Contextual information for the message request

Properties

Name	Type	Required	Restrictions	Description
userContext	string	false	none	Contextual information that is transfered back on delivery notifications.

MessageRequestOverrides

{
  "notificationCallbackUrl": "https://en4u5fpprib5i.x.pipedream.net"
}

Overrides of defaults for this message

Properties

Name	Type	Required	Restrictions	Description
notificationCallbackUrl	string	false	none	When present, this URL is used to send delivery notifications to your webhook. Can be used for debugging or individual routings.

WhatsAppProfile

{
  "address": "Hofmannstrasse 25 - 27, 81379 Munich, Germany",
  "description": "tyntec WhatsApp Business API Demo",
  "email": "support@tyntec.com",
  "websites": [
    "https://www.tyntec.com",
    "https://api.tyntec.com/reference"
  ],
  "vertical": "Professional Services",
  "about": "Hey there! I am using WhatsApp."
}

The current profile of a WhatsApp number.

Properties

Name	Type	Required	Restrictions	Description
address	string	false	none	Address of the business
description	string	false	none	Brief introduction of the business
email	string	false	none	Contact mail address
websites	[string]	false	none	Websites of the business
vertical	string	false	none	Industry of the business
about	string	false	none	Text to display in the About section of your profile

Enumerated values

Property	Value
vertical	Automotive
vertical	Beauty, Spa and Salon
vertical	Clothing and Apparel
vertical	Education
vertical	Entertainment
vertical	Event Planning and Service
vertical	Finance and Banking
vertical	Food and Grocery
vertical	Public Service
vertical	Hotel and Lodging
vertical	Medical and Health
vertical	Non-profit
vertical	Professional Services
vertical	Shopping and Retail
vertical	Travel and Transportation
vertical	Restaurant
vertical	Other

WhatsAppMessageStatusUpdate

{
  "status": "read"
}

Change in the message status of a previously sent WhatsApp message

Properties

Name	Type	Required	Restrictions	Description
status	string	false	none	WhatsApp message status

Enumerated values

Property	Value
status	read

WhatsAppProfileLogoLink

{
  "link": "https://pps.whatsapp.net/v/123123"
}

Link to the profile logo

Properties

Name	Type	Required	Restrictions	Description
link	string	true	none	Link to the profile logo

WhatsAppAccounts

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "whatsAppAccountName": "Swagger Sample Account",
    "businessName": "Swagger Sample business",
    "templateNamespace": "c9468969-a3a3-4c17-95f7-1e8b2902ed74",
    "facebookBusinessManagerId": 1791147717848878,
    "accountStatus": {
      "messageOnBehalf": "PENDING"
    },
    "managedBy": {
      "accountName": "tynteccpaas"
    }
  }
]

List of WhatsApp Business Accounts. Might be empty

Properties

Name	Type	Required	Restrictions	Description
anonymous	[WhatsAppAccount]	false	none	List of WhatsApp Business Accounts. Might be empty

WhatsAppAccount

{
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "whatsAppAccountName": "Swagger Sample Account",
  "businessName": "Swagger Sample business",
  "templateNamespace": "c9468969-a3a3-4c17-95f7-1e8b2902ed74",
  "facebookBusinessManagerId": 1791147717848878,
  "accountStatus": {
    "messageOnBehalf": "PENDING"
  },
  "managedBy": {
    "accountName": "tynteccpaas"
  }
}

A WhatsApp Business Account

Properties

Name	Type	Required	Restrictions	Description
whatsAppAccountId	string(uuid)	true	none	ID of the WhatsApp Business Account
whatsAppAccountName	string	false	none	Name of the WhatsApp Business Account
businessName	string	false	none	Name of the business owning the Facebook Business Manager
templateNamespace	string	false	none	Template namespace assigned to the WhatsApp Business Account. This is used internally and here stated for completeness.
facebookBusinessManagerId	string	false	none	The Facebook Business Manager ID provided by Facebook
whatsAppBusinessAccountId	string	false	none	The WhatsApp Business Account ID provided by WhatsApp
accountStatus	WhatsAppAccountStatus	false	none	Status information for the WhatsApp account
managedBy	CPaaSAccount	false	none	Account that can manage (edit, ...) an entity

WhatsAppPhoneNumbers

[
  {
    "phoneNumber": 4912345678,
    "displayPhonenumber": "+49 123 45678",
    "verifiedName": "Swagger Sample",
    "qualityRating": "YELLOW",
    "status": "FLAGGED",
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "managedBy": {
      "accountName": "tyntecscpaas"
    },
    "messagingVia": {
      "accountName": "messagingcpaas"
    }
  }
]

List of phone numbers at WhatsApp. Might be empty

Properties

Name	Type	Required	Restrictions	Description
anonymous	[WhatsAppPhoneNumber]	false	none	List of phone numbers at WhatsApp. Might be empty

WhatsAppPhoneNumber

{
  "phoneNumber": 4912345678,
  "displayPhonenumber": "+49 123 45678",
  "verifiedName": "Swagger Sample",
  "qualityRating": "YELLOW",
  "status": "FLAGGED",
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "managedBy": {
    "accountName": "tyntecscpaas"
  },
  "messagingVia": {
    "accountName": "messagingcpaas"
  }
}

A phone number assigned to a WhatsApp Business Account

Properties

Name	Type	Required	Restrictions	Description
phoneNumber	string	false	none	The phone number
displayPhoneNumber	string	false	none	The phone number as it is displayed in the app
verifiedName	string	false	none	The name shown aside to the number. This name will be shown immediately for Official Business Accounts.
qualityRating	string	false	none	The current quality rating of the phone number. A RED rating will lead to the `flagged` status if the number keeps receiving negative feedback from users.
status	string	false	none	Status of the number
whatsAppAccountId	string(uuid)	false	none	ID of the WhatsApp Business Account the number belongs to.
managedBy	CPaaSAccount	false	none	Account that can manage (edit, ...) an entity
messagingVia	CPaaSAccount	false	none	Account that must be used for messaging
messagingTier	string	false	none	Which messaging tier the number is currently on
qualityScore	QualityScore	false	none	The quality score provided by WhatsApp and calculated from user feedback on your messages

Enumerated values

Property	Value
qualityRating	GREEN
qualityRating	RED
qualityRating	YELLOW
status	CONNECTED
status	PENDING
status	FLAGGED
status	RESTRICTED
status	OFFLINE
messagingTier	TIER_NOT_SET
messagingTier	TIER_1K
messagingTier	TIER_10K
messagingTier	TIER_100K

CPaaSAccount

{
  "name": "someaccount"
}

The CPaaS account behind the API key

Properties

Name	Type	Required	Restrictions	Description
accountName	string	false	none	Name of the CPaaSAccount

WhatsAppTemplateRequest

{
  "name": "string",
  "category": "ACCOUNT_UPDATE",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "string"
        }
      ]
    }
  ]
}

Request for an additional WhatsApp template

Properties

Name	Type	Required	Restrictions	Description
name	string	false	none	Name of the template
category	TemplateCategory	false	none	Category of the template
localizations	[LocalizationRequest]	false	none	Localizations of the template

LocalizationRequest

{
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "string"
    }
  ]
}

Request for a new localization of a template

Properties

Name	Type	Required	Restrictions	Description
language	LanguageCode	false	none	Supported language codes, according to Supported Languages
components	any	false	none	Components defining the template

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	NotificationTemplateRequest	false	none	Request for a standard template (notification) without rich media components

xor

Name	Type	Required	Restrictions	Description
» anonymous	RichMediaTemplateRequest	false	none	Rich media template definition. Must contain at least the body component

NotificationTemplateRequest

[
  {
    "type": "BODY",
    "text": "string"
  }
]

Request for a standard template (notification) without rich media components

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Template component type. Always BODY
text	string	true	none	Template text (1--1024 chars)

Enumerated values

Property	Value
type	BODY

RichMediaTemplateRequest

[
  {
    "type": "HEADER",
    "format": "TEXT",
    "text": "Hi {{1}}",
    "example": {
      "text": "John Doe"
    }
  }
]

Rich media template definition. Must contain at least the body component

Properties

anyOf

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateHeaderComponentRequest	false	none	Header component of a template

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateBodyComponentRequest	false	none	Body component of a template

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateFooterComponentRequest	false	none	Footer component of a template

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateButtonComponentRequest	false	none	Button component of a template

WhatsAppTemplateHeaderComponentRequest

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Hi {{1}}",
  "example": {
    "text": "John Doe"
  }
}

Header component of a template

Properties

oneOf

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateTextHeaderComponentRequest	false	none	Text header component of a template

xor

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateMediaHeaderComponentRequest	false	none	Media header component of a template

xor

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppTemplateLocationHeaderComponentRequest	false	none	Location header component of a template

WhatsAppTemplateTextHeaderComponentRequest

{
  "type": "HEADER",
  "format": "TEXT",
  "text": "Hi {{1}}",
  "example": {
    "text": "John Doe"
  }
}

Text header component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component. Always HEADER
format	string	true	none	Which kind of header
text	string	true	none	Text that should be displayed as header. Can contain 1 variable
example	WhatsAppTemplateTextHeaderComponentRequestExample	false	none	Example of the header text

Enumerated values

Property	Value
type	HEADER
format	TEXT

WhatsAppTemplateTextHeaderComponentRequestExample

{
  "text": "John Doe"
}

Example of the header text

Properties

Name	Type	Required	Restrictions	Description
text	string	false	none	Example text

WhatsAppTemplateLocationHeaderComponentRequest

{
  "type": "HEADER",
  "format": "LOCATION"
}

Location header component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component. Always HEADER
format	string	true	none	Which kind of header

Enumerated values

Property	Value
type	HEADER
format	LOCATION

WhatsAppTemplateMediaHeaderComponentRequest

{
  "type": "HEADER",
  "format": "IMAGE",
  "example": {
    "url": "https://www.my.com/image.jpg"
  }
}

Media header component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component. Always HEADER
format	string	true	none	Which kind of header
example	WhatsAppTemplateMediaHeaderComponentRequestExample	false	none	Example of a media

Enumerated values

Property	Value
type	HEADER
format	IMAGE
format	DOCUMENT
format	VIDEO

WhatsAppTemplateMediaHeaderComponentRequestExample

{
  "url": "https://www.my.com/image.jpg"
}

Example of a media

Properties

Name	Type	Required	Restrictions	Description
url	string	false	none	URL of the example media file

WhatsAppTemplateBodyComponentRequest

{
  "type": "BODY",
  "text": "Hi {{1}}, your order {{2}} is shipped",
  "example": {
    "texts": [
      "John Doe",
      123
    ]
  }
}

Body component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component. Always BODY
text	string	true	none	Specification of the body text (1--160 chars)
example	WhatsAppTemplateBodyComponentRequestExample	false	none	Examples of the body parameters. All parameters of the body must have an example

Enumerated values

Property	Value
type	BODY

WhatsAppTemplateBodyComponentRequestExample

{
  "texts": [
    "John Doe",
    "Order ID 123"
  ]
}

Examples of the body parameters. All parameters of the body must have an example

Properties

Name	Type	Required	Restrictions	Description
texts	[string]	false	none	Examples of the body parameters

WhatsAppTemplateFooterComponentRequest

{
  "type": "FOOTER",
  "text": "The specification team"
}

Footer component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component
text	string	true	none	Specification of the footer text (1--60 chars)

Enumerated values

Property	Value
type	FOOTER

WhatsAppTemplateButtonComponentRequest

{
  "type": "BUTTONS",
  "buttons": [
    {
      "type": "QUICK_REPLY",
      "text": "I liked it!"
    }
  ]
}

Button component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Determines the type of the component
buttons	any	true	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppQuickReplyButtons	false	none	Quick Reply buttons

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppCallToActionButtons	false	none	Call to action buttons. At most one of each button type can be used.

Enumerated values

Property	Value
type	BUTTONS

WhatsAppQuickReplyButtons

[
  {
    "type": "QUICK_REPLY",
    "text": "I liked it!"
  }
]

Quick Reply buttons

Properties

Name	Type	Required	Restrictions	Description
anonymous	[WhatsAppQuickReplyButton]	false	none	Quick Reply buttons

WhatsAppQuickReplyButton

{
  "type": "QUICK_REPLY",
  "text": "I liked it!"
}

Quick reply button, when clicked the caption and the dynamic payload is returned.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Type of this button
text	string	true	none	Caption of the button

Enumerated values

Property	Value
type	QUICK_REPLY

WhatsAppCallToActionButtons

[
  {
    "type": "URL",
    "text": "Your invoice",
    "url": "https://www.myservice.com/invoices/{{1}}",
    "example": {
      "url": "https://www.myservice.com/invoices/9424a5c5-9089-4142-9cd2-0365383ce387.pdf"
    }
  }
]

Call to action buttons. At most one of each button type can be used.

Properties

anyOf

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppURLButton	false	none	Call to action button that opens the specified URL when clicked

Name	Type	Required	Restrictions	Description
anonymous	WhatsAppPhoneNumberButton	false	none	Call to action button that initiates a call when clicked

WhatsAppURLButton

{
  "type": "URL",
  "text": "Your invoice",
  "url": "https://www.myservice.com/invoices/{{1}}",
  "example": {
    "url": "https://www.myservice.com/invoices/9424a5c5-9089-4142-9cd2-0365383ce387.pdf"
  }
}

Call to action button that opens the specified URL when clicked

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Type of this button
text	string	true	none	Caption of the button
url	string	false	none	the URL that will be openend when clicking on the button. Can contain 1 parameter at the end.
example	WhatsAppURLButtonExample	false	none	Example for a dynamic URL button.

Enumerated values

Property	Value
type	URL

WhatsAppURLButtonExample

{
  "url": "https://www.myservice.com/invoices/9424a5c5-9089-4142-9cd2-0365383ce387.pdf"
}

Example for a dynamic URL button.

Properties

Name	Type	Required	Restrictions	Description
url	string	false	none	Example for a dynamic URL button. Must start with the same base url as the url button

WhatsAppPhoneNumberButton

{
  "type": "PHONE_NUMBER",
  "text": "Call us",
  "phoneNumber": "+4923147790813"
}

Call to action button that initiates a call when clicked

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Type of this button
text	string	true	none	Caption of this button
phoneNumber	string	false	none	Phone number that will be called when clicking on the button.

Enumerated values

Property	Value
type	PHONE_NUMBER

WhatsAppTemplates

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "name": "swagger_test",
    "category": "TICKET_UPDATE",
    "localizations": [
      {
        "status": "REJECTED",
        "rejectionReason": "For this example",
        "language": "en",
        "components": [
          {
            "type": "BODY",
            "text": "Hello {{1}}! How is going?"
          },
          {
            "type": "FOOTER",
            "text": "Your specification team!"
          }
        ]
      }
    ]
  }
]

List of WhatsApp templates

Properties

Name	Type	Required	Restrictions	Description
anonymous	[WhatsAppTemplateResponse]	false	none	List of WhatsApp templates

WhatsAppTemplateResponse

{
  "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
  "name": "swagger_test",
  "category": "TICKET_UPDATE",
  "localizations": [
    {
      "status": "REJECTED",
      "rejectionReason": "For this example",
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hello {{1}}! How is going?"
        },
        {
          "type": "FOOTER",
          "text": "Your specification team!"
        }
      ]
    }
  ]
}

WhatsApp template

Properties

Name	Type	Required	Restrictions	Description
whatsAppAccountId	string(uuid)	false	none	ID of the WhatsApp Business Account the template belongs to.
templateName	string	false	none	Name of the template
templateId	string	false	none	ID of the template
category	TemplateCategory	false	none	Category of the template
localízations	[LocalizationResponse]	false	none	List of localizations of this templates

LocalizationResponse

{
  "status": "DELETED",
  "rejectionReason": "not yet",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "Hello {{1}}! How is going?"
    }
  ],
  "createdAt": "2020-02-15T23:28:34.442Z",
  "lastUpdated": "2020-02-15T25:28:34.442Z",
  "expiresAt": "2020-03-15T23:28:34.442Z",
  "qualityScore": {
    "score": "RED",
    "reasons": [
      "Users are choosing \"didn't sign up\" as a reason for blocking this phone number. Businesses must obtain opt-in before sending notifications. Please review your opt-in flow(s) and see our Business Policy for more detail."
    ]
  }
}

Localization of a template

Properties

Name	Type	Required	Restrictions	Description
status	string	true	none	Status the localization.
rejectionReason	string	false	none	Descriptive text in the case the status is REJECTED
language	LanguageCode	true	none	Supported language codes, according to Supported Languages
components	[anyOf]	true	none	Set of components defining a template

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppTemplateHeaderComponentResponse	false	none	Header component of a template

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppTemplateBodyComponentResponse	false	none	Body component of a template

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppTemplateFooterComponentResponse	false	none	Footer component of a template

continued

Name	Type	Required	Restrictions	Description
createdAt	string(date-time)	true	none	At which point in time the template was created
lastUpdated	string(date-time)	true	none	At which point in time the last update happened
expiresAt	string(date-time)	false	none	When does the localization expire. Only present when a template was deleted.
qualityScore	QualityScore	false	none	The quality score provided by WhatsApp and calculated from user feedback on your messages

Enumerated values

Property	Value
status	REQUESTED
status	SUBMIT_FAILED
status	PENDING
status	APPROVED
status	REJECTED
status	DELETION_PENDING
status	DELETED
status	SUBMITTED

WhatsAppTemplateHeaderComponentResponse

{
  "type": "HEADER",
  "format": "IMAGE",
  "text": "Hi {{1}}!"
}

Header component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Component type
format	string	true	none	Which kind of header
text	string	false	none	Text based part of format "TEXT

Enumerated values

Property	Value
type	HEADER
format	IMAGE
format	TEXT
format	DOCUMENT
format	VIDEO

WhatsAppTemplateBodyComponentResponse

{
  "type": "BODY",
  "text": "Hi {{1}}! Enjoy the spec!"
}

Body component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Component type
text	string	true	none	Specification of the body text

Enumerated values

Property	Value
type	BODY

WhatsAppTemplateFooterComponentResponse

{
  "type": "FOOTER",
  "text": "The specification team"
}

Footer component of a template

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Component type
text	string	true	none	Specification of the footer text

Enumerated values

Property	Value
type	FOOTER

TemplateCategory

"ACCOUNT_UPDATE"

Category of the template

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Category of the template

Enumerated values

Property	Value
anonymous	ACCOUNT_UPDATE
anonymous	ALERT_UPDATE
anonymous	APPOINTMENT_UPDATE
anonymous	AUTO_REPLY
anonymous	ISSUE_RESOLUTION
anonymous	PAYMENT_UPDATE
anonymous	PERSONAL_FINANCE_UPDATE
anonymous	RESERVATION_UPDATE
anonymous	SHIPPING_UPDATE
anonymous	TICKET_UPDATE
anonymous	TRANSPORTATION_UPDATE

LanguageCode

"en"

Supported language codes, according to Supported Languages

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Supported language codes, according to Supported Languages

Enumerated values

Property	Value
anonymous	af
anonymous	ar
anonymous	az
anonymous	bg
anonymous	bn
anonymous	ca
anonymous	cs
anonymous	da
anonymous	de
anonymous	el
anonymous	en
anonymous	en_GB
anonymous	en_US
anonymous	es
anonymous	es_AR
anonymous	es_ES
anonymous	es_MX
anonymous	et
anonymous	fa
anonymous	fi
anonymous	fil
anonymous	fr
anonymous	ga
anonymous	gu
anonymous	ha
anonymous	he
anonymous	hi
anonymous	hr
anonymous	hu
anonymous	ID
anonymous	it
anonymous	ja
anonymous	kk
anonymous	kn
anonymous	ko
anonymous	lo
anonymous	lt
anonymous	lv
anonymous	mk
anonymous	ml
anonymous	mr
anonymous	ms
anonymous	nb
anonymous	nl
anonymous	pa
anonymous	pl
anonymous	pt_BR
anonymous	pt_PT
anonymous	ro
anonymous	ru
anonymous	sk
anonymous	sl
anonymous	sq
anonymous	sr
anonymous	sv
anonymous	sw
anonymous	ta
anonymous	te
anonymous	th
anonymous	tr
anonymous	uk
anonymous	ur
anonymous	uz
anonymous	vi
anonymous	zh_CN
anonymous	zh_HK
anonymous	zh_TW
anonymous	zu

WhatsAppAccountStatus

{
  "messageOnBehalf": "APPROVED"
}

Status information for the WhatsApp account

Properties

Name	Type	Required	Restrictions	Description
messageOnBehalf	string	false	none	Indicates the status of a message on behalf request

Enumerated values

Property	Value
messageOnBehalf	PENDING
messageOnBehalf	APPROVED
messageOnBehalf	DENIED

PaginationLinkRelation

"first"

What kind of relation is this link.

The relations are defined as follows:

first – The first page in the resource list pagination
previous – The preceding page in the resource list pagination
current – The current page in the resource list pagination
next – The following page in the resource list pagination
last – The last page in the resource list pagination

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	What kind of relation is this link. The relations are defined as follows: - `first` – The first page in the resource list pagination - `previous` – The preceding page in the resource list pagination - `current` – The current page in the resource list pagination - `next` – The following page in the resource list pagination - `last` – The last page in the resource list pagination

Enumerated values

Property	Value
anonymous	first
anonymous	previous
anonymous	current
anonymous	next
anonymous	last

BulkRequest

{
  "to": "string",
  "from": "string",
  "channel": "whatsapp",
  "whatsapp": [
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    },
    {
      "contentType": "template",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
      "media": {
        "type": "audio",
        "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
      },
      "template": {
        "templateId": "weclome_message",
        "language": {
          "policy": "deterministic",
          "code": "en"
        },
        "components": [
          {
            "type": "header",
            "parameters": [
              {
                "type": "media",
                "media": {
                  "type": "image",
                  "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
                }
              }
            ]
          },
          {
            "type": "body",
            "parameters": [
              {
                "type": "text",
                "text": "Hi!"
              }
            ]
          }
        ]
      },
      "location": {
        "longitude": 7.4954884,
        "latitude": 51.5005765,
        "name": "tyntec GmbH",
        "address": "tyntec GmbH, Semerteichstraße, Dortmund"
      },
      "urlPreviewDisplayed": true,
      "contacts": [
        {
          "birthday": "2018-01-01",
          "addresses": [
            {
              "city": "Dortmund",
              "country": "Germany",
              "countryCode": "de",
              "state": "NRW",
              "street": "string",
              "type": "WORK",
              "zip": 44231
            }
          ],
          "emails": [
            {
              "email": "whatsapp@tyntec.com",
              "type": "WORK"
            }
          ],
          "ims": [
            {
              "service": "WhatsApp",
              "userId": 123123123
            }
          ],
          "name": {
            "prefix": "Mr.",
            "firstName": "Peter",
            "middleName": "Michael",
            "lastName": "Tyntec",
            "suffix": "senior",
            "formattedName": "Mr. Peter Michael Tyntec senior"
          },
          "org": {
            "company": "tyntec GmbH",
            "department": "Development",
            "title": "API Guardian"
          },
          "phones": [
            {
              "phone": "+49 231 477 90 813",
              "type": "WORK"
            }
          ],
          "urls": [
            {
              "url": "https://www.tyntec.com",
              "type": "WORK"
            }
          ]
        }
      ]
    }
  ]
}

Bulk request to be sent. The items are guaranteed to be sent in order of appearance

Properties

Name	Type	Required	Restrictions	Description
to	string	false	none	none
from	string	false	none	none
channel	string	false	none	Channel which should be used for the bulk
whatsapp	[BulkWhatsAppRequest]	false	none	WhatsApp messages to be sent (2--20 messages)

Enumerated values

Property	Value
channel	whatsapp

BulkWhatsAppRequest

{
  "contentType": "template",
  "text": "Thanks for contacting our support. We will get back to you in 5 minutes.",
  "media": {
    "type": "audio",
    "url": "https://dl.espressif.com/dl/audio/ff-16b-2c-44100hz.mp4"
  },
  "template": {
    "templateId": "weclome_message",
    "language": {
      "policy": "deterministic",
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "media",
            "media": {
              "type": "image",
              "url": "https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.png"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Hi!"
          }
        ]
      }
    ]
  },
  "location": {
    "longitude": 7.4954884,
    "latitude": 51.5005765,
    "name": "tyntec GmbH",
    "address": "tyntec GmbH, Semerteichstraße, Dortmund"
  },
  "urlPreviewDisplayed": true,
  "contacts": [
    {
      "birthday": "2018-01-01",
      "addresses": [
        {
          "city": "Dortmund",
          "country": "Germany",
          "countryCode": "de",
          "state": "NRW",
          "street": "string",
          "type": "WORK",
          "zip": 44231
        }
      ],
      "emails": [
        {
          "email": "whatsapp@tyntec.com",
          "type": "WORK"
        }
      ],
      "ims": [
        {
          "service": "WhatsApp",
          "userId": 123123123
        }
      ],
      "name": {
        "prefix": "Mr.",
        "firstName": "Peter",
        "middleName": "Michael",
        "lastName": "Tyntec",
        "suffix": "senior",
        "formattedName": "Mr. Peter Michael Tyntec senior"
      },
      "org": {
        "company": "tyntec GmbH",
        "department": "Development",
        "title": "API Guardian"
      },
      "phones": [
        {
          "phone": "+49 231 477 90 813",
          "type": "WORK"
        }
      ],
      "urls": [
        {
          "url": "https://www.tyntec.com",
          "type": "WORK"
        }
      ]
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
contentType	string	false	none	What kind of payload is used
text	string	false	none	The text to be sent
media	Media	false	none	Media file to be sent
template	Template	false	none	The message template to be sent.
location	Location	false	none	Location received or sent
urlPreviewDisplayed	boolean	false	none	Should a preview of the URL be rendered. This will only have an effect on text messages.
contacts	[Contact]	false	none	[Contact object]

Enumerated values

Property	Value
contentType	template
contentType	text
contentType	url
contentType	media
contentType	location
contentType	contacts

QualityScore

{
  "score": "RED",
  "reasons": [
    "Users are choosing \"didn't sign up\" as a reason for blocking this phone number. Businesses must obtain opt-in before sending notifications. Please review your opt-in flow(s) and see our Business Policy for more detail."
  ]
}

The quality score provided by WhatsApp and calculated from user feedback on your messages

Properties

Name	Type	Required	Restrictions	Description
score	string	true	none	The current scoring
reasons	[string]	false	none	Textual description why the quality score is set to the value. Only present when score is YELLOW or RED

Enumerated values

Property	Value
score	unknown
score	GREEN
score	YELLOW
score	RED

WhatsAppTextHeaderComponent

{
  "type": "text",
  "text": "string"
}

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	none
text	string	false	none	none

Enumerated values

Property	Value
type	text

BaseMedia

{
  "url": "string"
}

Base object handling media definitions for sending.

Properties

Name	Type	Required	Restrictions	Description
url	string	false	none	the url of the location where the media is stored

WhatsAppMediaHeader

{
  "url": "string"
}

Document media specification

Properties

None

WhatsAppDocumentHeader

{
  "filename": "Test PDF",
  "url": "string"
}

Document media specification

Properties

Name	Type	Required	Restrictions	Description
filename	string	false	none	Additional info for the filename to be displayed.

WhatsAppImageHeaderComponent

{
  "type": "image",
  "image": {
    "url": "string"
  }
}

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	none
image	WhatsAppMediaHeader	false	none	Document media specification

Enumerated values

Property	Value
type	image

WhatsAppVideoHeaderComponent

{
  "type": "video",
  "video": {
    "url": "string"
  }
}

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	none
video	WhatsAppMediaHeader	false	none	Document media specification

Enumerated values

Property	Value
type	video

WhatsAppDocumentHeaderComponent

{
  "type": "document",
  "document": {
    "filename": "Test PDF",
    "url": "string"
  }
}

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	none
document	WhatsAppDocumentHeader	false	none	Document media specification

Enumerated values

Property	Value
type	document

WhatsAppInteractiveFooterContent

{
  "contentType": "text",
  "text": "string"
}

Properties

Name	Type	Required	Restrictions	Description
contentType	string	false	none	none
text	string	false	none	none

Enumerated values

Property	Value
contentType	text

WhatsAppInteractiveTextContent

{
  "contentType": "text",
  "text": "string"
}

Properties

Name	Type	Required	Restrictions	Description
contentType	string	false	none	none
text	string	false	none	none

Enumerated values

Property	Value
contentType	text

WhatsAppInteractiveButtonMessage

{
  "subtype": "buttons",
  "components": {
    "header": {
      "type": "text",
      "text": "Your request is queued"
    },
    "body": {
      "type": "text",
      "text": "How would you rate your bot experience"
    },
    "footer": {
      "type": "text",
      "text": "Your service bot"
    },
    "buttons": [
      {
        "type": "reply",
        "reply": {
          "payload": "987298-40980jvkdm9-234234234",
          "title": "Poor"
        }
      },
      {
        "type": "reply",
        "reply": {
          "payload": "987298-dsfgjlkhgdf-dg09u834334",
          "title": "OK"
        }
      },
      {
        "type": "reply",
        "reply": {
          "payload": "9080923445nlkjß0_gß0923845083245dfg",
          "title": "Good"
        }
      }
    ]
  }
}

Interactive message type

Properties

Name	Type	Required	Restrictions	Description
subtype	string	true	none	none
components	WhatsAppInteractiveButtonComponents	true	none	none

Enumerated values

Property	Value
subtype	buttons

WhatsAppInteractiveListMessage

{
  "subtype": "list",
  "components": {
    "header": {
      "type": "text",
      "text": "Choose your menu"
    },
    "body": {
      "type": "text",
      "text": "Hi Sarah, select your menu from the bottom list. Dressings and toppings are selected later on"
    },
    "footer": {
      "type": "text",
      "text": "Your tyntec food team"
    },
    "list": {
      "title": "Your menu",
      "sections": [
        {
          "title": "Vegan",
          "rows": [
            {
              "title": "Green dream",
              "payload": "green-dream-34987-234897234-234",
              "description": "A bowl full of tasty leaves, soy beans and cucumber"
            },
            {
              "title": "Rainbow meets rice",
              "payload": "rainbow-meets-rice-34987-234897234-234",
              "description": "A colorful selection of vegetables on a cozy bed of basmati rice"
            }
          ]
        },
        {
          "title": "Vegetarian",
          "rows": [
            {
              "title": "Italo Classic",
              "payload": "italo-classic-34987-234897234-234",
              "description": "Slices of tomates, with plucked pieces of mozzarella and basil leaves"
            },
            {
              "title": "Egg & Peas",
              "payload": "egg-and-peas-34987-234897234-234",
              "description": "Tasty slices of eggs, on a whole wheat pasta salad with peas"
            }
          ]
        }
      ]
    }
  }
}

Interactive message type

Properties

Name	Type	Required	Restrictions	Description
subtype	string	true	none	none
components	WhatsAppInteractiveListComponents	true	none	List message component. It can have at most 10 rows distributed over at most 10 sections

Enumerated values

Property	Value
subtype	list

WhatsAppInteractiveButtonComponents

{
  "header": {
    "type": "text",
    "text": "string"
  },
  "body": {
    "contentType": "text",
    "text": "string"
  },
  "footer": {
    "contentType": "text",
    "text": "string"
  },
  "buttons": [
    {
      "type": "reply",
      "reply": {
        "payload": "string",
        "title": "string"
      }
    }
  ]
}

Properties

Name	Type	Required	Restrictions	Description
header	any	false	none	none

oneOf

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppTextHeaderComponent	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppImageHeaderComponent	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppVideoHeaderComponent	false	none	none

xor

Name	Type	Required	Restrictions	Description
» anonymous	WhatsAppDocumentHeaderComponent	false	none	none

continued

Name	Type	Required	Restrictions	Description
body	WhatsAppInteractiveTextContent	true	none	none
footer	WhatsAppInteractiveFooterContent	false	none	none
buttons	[WhatsAppInteractiveButton]	true	none	[Interactive message button]

WhatsAppInteractiveButton

{
  "type": "reply",
  "reply": {
    "payload": "string",
    "title": "string"
  }
}

Interactive message button

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	Type of the button. Always "reply"
reply	object	true	none	Reply button specification
» payload	string	true	none	ID of the reply button. Must be unique within the same messaging request
» title	string	true	none	Caption or title of the button

Enumerated values

Property	Value
type	reply

WhatsAppInteractiveListComponents

{
  "header": {
    "type": "text",
    "text": "string"
  },
  "body": {
    "contentType": "text",
    "text": "string"
  },
  "footer": {
    "contentType": "text",
    "text": "string"
  },
  "list": {
    "title": "Choose from this list",
    "sections": [
      {
        "title": "string",
        "rows": [
          {
            "payload": "string",
            "title": "string",
            "description": "string"
          }
        ]
      }
    ]
  }
}

List message component. It can have at most 10 rows distributed over at most 10 sections

Properties

Name	Type	Required	Restrictions	Description
header	WhatsAppTextHeaderComponent	false	none	none
body	WhatsAppInteractiveTextContent	true	none	none
footer	WhatsAppInteractiveFooterContent	false	none	none
list	WhatsAppInteractiveListContent	true	none	Definition of a WhatsApp interactive list

WhatsAppInteractiveListContent

{
  "title": "Choose from this list",
  "sections": [
    {
      "title": "string",
      "rows": [
        {
          "payload": "string",
          "title": "string",
          "description": "string"
        }
      ]
    }
  ]
}

Definition of a WhatsApp interactive list

Properties

Name	Type	Required	Restrictions	Description
title	string	true	none	none
sections	[WhatsAppListSection]	true	none	Sections of the list message

WhatsAppListSection

{
  "title": "string",
  "rows": [
    {
      "payload": "string",
      "title": "string",
      "description": "string"
    }
  ]
}

Section of a list message.

Properties

Name	Type	Required	Restrictions	Description
title	string	false	none	Title of the section mandatory in case of multiple sections
rows	[WhatsAppListSectionRow]	true	none	Items of the section

WhatsAppListSectionRow

{
  "payload": "string",
  "title": "string",
  "description": "string"
}

Row item of a list message

Properties

Name	Type	Required	Restrictions	Description
payload	string	true	none	ID of the item, must be unique within the request
title	string	true	none	Caption of the item in the list
description	string	false	none	Optional description of the item

Viber

Version: v2.13

Specification Release Notes Postman Collection Other versions

Conversations allows you to easily send messages to your customers via Viber.

Channel specific pre-conditions

Viber : A Viber Service id is required in order to use this channel. Please request access here

Viber defines different rate types and capabilities. The rate types limit the possible content combinations.

The following content / rate type combinations are valid

Rate Type	Text	Image	File	Text & Button	Text & Button & Image
Transaction	✔	❌	❌	❌	❌
Promotion	✔	✔	✔	✔	✔
Session	✔	✔	✔	✔	✔

The rate types have as well consequences on the charging applied by viber per message.

Base URLs

https://api.tyntec.com/chat-api/v2

Messaging

In this section we guide you on how to send messages, get information about the status and the events happening during the delivery

Send a message

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/messages HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "12331132",
  "channels": [
    "viber"
  ],
  "viber": {
    "from": "1233423454",
    "components": [
      {
        "type": "text",
        "text": "hi!"
      }
    ]
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/messages',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/messages', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/messages', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/messages", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /messages

Send chat messages via this path.

Body parameter

{
  "to": "12331132",
  "channels": [
    "viber"
  ],
  "viber": {
    "from": "1233423454",
    "components": [
      {
        "type": "text",
        "text": "hi!"
      }
    ]
  }
}

Parameters

Name	In	Type	Required	Description
body	body	MessageRequest	true	The message you would like to send

Example responses

202 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The message is accepted by our system	MessageResponse
400	Bad Request	The request does not match our expectations. Please check the Problems object for details	Problem
403	Forbidden	You attempting to use a number that is not assigned to your account	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Retrieve the message

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}

Returns back a message previously send by you.

Important After a final status notification (delivered, read or failed) the message is only available for the next 48 hours. After this period we delete the message in our system.

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The message ID requested exists.	StoredMessage
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Send a bulk of messages

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/bulks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/bulks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "string",
  "from": "string",
  "channel": "viber",
  "viber": [
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    },
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/bulks',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/bulks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/bulks', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/bulks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/bulks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/bulks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /bulks

Send a bulk of messages via one channel to one recipient.

The system guarantees that the messages are send in order to the recipient

Body parameter

{
  "to": "string",
  "from": "string",
  "channel": "viber",
  "viber": [
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    },
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	BulkRequest	true	The message bulk you want to send

Example responses

202 Response

{
  "bulkId": "77185196-664a-43ec-b14a-fe97036c697f",
  "messageIds": [
    "77185196-664a-43ec-b14a-fe97036c697f",
    "77185196-664a-43ec-b14a-fe97036c697f"
  ]
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The requested bulk was accepted	Inline
400	Bad Request	The request does not match our expectations. Please check the Problems object for details	Problem
403	Forbidden	You attempting to use a number that is not assigned to your account	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Response Schema

Status Code 202

Name	Type	Required	Restrictions	Description
» bulkId	string(uuid)	false	none	none
» messageIds	[string]	false	none	none

Schemas

MessageRequest

{
  "to": "+123234234",
  "channels": [
    "viber"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

The message you would like to send

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient of the message. Could be one of - phone number in international format. In this it should follow the guidelines of E.164 but leading 00 is as well accepted - group ID create via the WA Group management
channels	[string]	true	none	Channels selected for delivery.
overrides	MessageRequestOverrides	false	none	Overrides of defaults for this message
context	MessageRequestContext	false	none	Contextual information for the message request
viber	ViberMessageRequest	false	none	Viber message to be sent

StoredMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient phone number in international format. It should follow the guidelines of E.164 but leading 00 is as well accepted
channels	[string]	true	none	Channels selected for delivery.
viber	ViberMessageRequest	false	none	Viber message to be sent

ViberMessageRequest

{
  "from": "1233423454",
  "messagePurpose": "transaction",
  "components": [
    {
      "type": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    }
  ]
}

Viber message to be sent

Properties

Name	Type	Required	Restrictions	Description
from	string	false	none	Viber channel ID
components	[anyOf]	true	none	Components to be used for sending a viber message. Only these combinations are supported - text - image - file - text & button - text & image & button

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	ViberTextComponent	false	none	Text component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberImageComponent	false	none	Image component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberFileComponent	false	none	File component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberButtonComponent	false	none	Button component for viber

continued

Name	Type	Required	Restrictions	Description
messagePurpose	string	false	none	Alias for rate type
rateType	string	false	none	Rate type of the message

Enumerated values

Property	Value
messagePurpose	promotion
messagePurpose	transaction
messagePurpose	session
rateType	promotion
rateType	transaction
rateType	session

ViberTextComponent

{
  "type": "text",
  "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
}

Text component for viber

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Text component for viber
text	string	false	none	The message to be sent

Enumerated values

Property	Value
type	text

ViberButtonComponent

{
  "type": "button",
  "button": {
    "caption": "click me!",
    "callback": "https://my.callba.ck/clicked"
  }
}

Button component for viber

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	none
button	object	false	none	The button to be used
» caption	string	false	none	Caption of the button
» callback	string	false	none	Action callback that is executed when the user clicks on the button

Enumerated values

Property	Value
type	button

ViberImageComponent

{
  "type": "image",
  "image": {
    "url": "string"
  }
}

Image component for viber

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Image component for Viber
image	object	false	none	The image to be sent
» url	string	false	none	Url location of the image, must be accessible from the public network

Enumerated values

Property	Value
type	image

ViberFileComponent

{
  "type": "file",
  "file": {
    "url": "string",
    "filename": "string",
    "type": "doc"
  }
}

File component for viber

Properties

Name	Type	Required	Restrictions	Description
type	string	false	none	Defines the content type. Always file
file	object	false	none	The file to be sent
» url	string	false	none	Public available URL of the file. The file URL will be used on the app to provide the user with the file.
» filename	string	false	none	Name of the file presented on the app
» type	string	false	none	This parameter can be set to specify the file type. If not present, the file type is deducted from the URL given.

Enumerated values

Property	Value
type	file
type	doc
type	docx
type	rtf
type	dot
type	dotx
type	odt
type	odf
type	fodt
type	txt
type	info
type	pdf
type	xps
type	pdax
type	eps
type	xls
type	xlsx
type	ods
type	fods
type	csv
type	xlsm
type	xltx

MessageResponse

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string(uuid)	true	none	Global Message ID reference
acceptedAt	string(date-time)	true	none	Point in time when the API confirms that the message request was accepted

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows the RFC-7807 (https://tools.ietf.org/html/rfc7807)

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference [RFC3986] that identifies the problem type
title	string	true	none	A short, human-readable summary of the problem type.
status	string	true	none	The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail	string	true	none	A human-readable explanation specific to this occurrence of the problem.

MessageRequestContext

{
  "userContext": "my-message-reference"
}

Contextual information for the message request

Properties

Name	Type	Required	Restrictions	Description
userContext	string	false	none	Contextual information that is transfered back on delivery notifications.

MessageRequestOverrides

{
  "notificationCallbackUrl": "https://en4u5fpprib5i.x.pipedream.net"
}

Overrides of defaults for this message

Properties

Name	Type	Required	Restrictions	Description
notificationCallbackUrl	string	false	none	When present this url is used for sending the delivery notifications to your webhook. Can be used for debugging use cases or individual routings.

BulkRequest

{
  "to": "string",
  "from": "string",
  "channel": "viber",
  "viber": [
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    },
    {
      "components": [
        {
          "type": "text",
          "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
        }
      ],
      "messagePurpose": "promotion"
    }
  ]
}

Bulk request to be sent. The items are guaranted to be sent in order of appearance

Properties

Name	Type	Required	Restrictions	Description
to	string	false	none	none
from	string	false	none	none
channel	string	false	none	Channel which should be used for the bulk
viber	[BulkViberRequest]	false	none	Viber messages to be sent

Enumerated values

Property	Value
channel	viber

BulkViberRequest

{
  "components": [
    {
      "type": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    }
  ],
  "messagePurpose": "promotion"
}

Properties

Name	Type	Required	Restrictions	Description
components	[anyOf]	false	none	Components to be used for sending a viber message. Only these combinations are supported - text - image - file - text & button - text & image & button

anyOf

Name	Type	Required	Restrictions	Description
» anonymous	ViberTextComponent	false	none	Text component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberImageComponent	false	none	Image component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberFileComponent	false	none	File component for viber

Name	Type	Required	Restrictions	Description
» anonymous	ViberButtonComponent	false	none	Button component for viber

continued

Name	Type	Required	Restrictions	Description
messagePurpose	string	false	none	Purpose of the message

Enumerated values

Property	Value
messagePurpose	promotion
messagePurpose	transaction

SMS

Version: v2.12

Specification Release Notes Postman Collection Other versions

Conversations allows you to easily reach out and communicate with your clients via 2-way SMS.

Channel specific prerequisites

2-way SMS: Please contact us to get the details for the 2-way SMS setup

Base URLs

https://api.tyntec.com/chat-api/v2

Messaging

In this section we guide you on how to send messages, get information about the status and the events happening during the delivery

Send a message

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/messages HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "12331132",
  "channels": [
    "sms"
  ],
  "sms": {
    "from": "1233423454",
    "contentType": "text",
    "text": "hi!"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/messages',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/messages', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/messages', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/messages", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /messages

Send chat messages via this path.

Body parameter

{
  "to": "12331132",
  "channels": [
    "sms"
  ],
  "sms": {
    "from": "1233423454",
    "contentType": "text",
    "text": "hi!"
  }
}

Parameters

Name	In	Type	Required	Description
body	body	MessageRequest	true	The message you would like to send

Example responses

202 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The message is accepted by our system	MessageResponse
400	Bad Request	The request does not match our expectations. Please check the Problems object for details	Problem
403	Forbidden	You attempting to use a number that is not assigned to your account	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Retrieve the message

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/messages/{message-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/messages/{message-id} HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/messages/{message-id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/messages/{message-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/messages/{message-id}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/messages/{message-id}', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/messages/{message-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/messages/{message-id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /messages/{message-id}

Returns back a message previously send by you.

Important After a final status notification (delivered, read or failed) the message is only available for the next 48 hours. After this period we delete the message in our system.

Parameters

Name	In	Type	Required	Description
message-id	path	string(uuid)	true	The ID of the message

Example responses

200 Response

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "sms"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

404 Response

{
  "status": 404
}

Responses

Status	Meaning	Description	Schema
200	OK	The message ID requested exists.	StoredMessage
404	Not Found	The message ID does not exist in our system	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Send a bulk of messages

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/chat-api/v2/bulks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/chat-api/v2/bulks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "to": "string",
  "from": "string",
  "channel": "sms",
  "sms": [
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    },
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/bulks',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/chat-api/v2/bulks',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.post('https://api.tyntec.com/chat-api/v2/bulks', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','https://api.tyntec.com/chat-api/v2/bulks', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/bulks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/chat-api/v2/bulks", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

POST /bulks

Send a bulk of messages via one channel to one recipient.

The system guarantees that the messages are send in order to the recipient

Body parameter

{
  "to": "string",
  "from": "string",
  "channel": "sms",
  "sms": [
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    },
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	BulkRequest	true	The message bulk you want to send

Example responses

202 Response

{
  "bulkId": "77185196-664a-43ec-b14a-fe97036c697f",
  "messageIds": [
    "77185196-664a-43ec-b14a-fe97036c697f",
    "77185196-664a-43ec-b14a-fe97036c697f"
  ]
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

403 Response

{
  "type": "https://httpstatuses.com/403",
  "title": "Forbidden",
  "status": 403
}

Responses

Status	Meaning	Description	Schema
202	Accepted	The requested bulk was accepted	Inline
400	Bad Request	The request does not match our expectations. Please check the Problems object for details	Problem
403	Forbidden	You attempting to use a number that is not assigned to your account	Problem
default	Default	Default response in case of any other error. Please check the error object for details	Problem

Response Schema

Status Code 202

Name	Type	Required	Restrictions	Description
» bulkId	string(uuid)	false	none	none
» messageIds	[string]	false	none	none

Schemas

MessageRequest

{
  "to": "+123234234",
  "channels": [
    "sms"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

The message you would like to send

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient of the message. Could be one of - phone number in international format. In this it should follow the guidelines of E.164 but leading 00 is as well accepted - group ID create via the WA Group management
channels	[string]	true	none	Channels selected for delivery.
overrides	MessageRequestOverrides	false	none	Overrides of defaults for this message
context	MessageRequestContext	false	none	Contextual information for the message request
sms	SMSRequest	false	none	Normal SMS to be sent. If Content is used as well this will override the specification made there. In case URL type is specified the recipient will receive the plain URL as SMS.

StoredMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "to": "+123234234",
  "channels": [
    "sms"
  ],
  "whatsapp": {
    "from": "545345345",
    "contentType": "text",
    "text": "A simple text message"
  }
}

Properties

Name	Type	Required	Restrictions	Description
to	string	true	none	The recipient phone number in international format. It should follow the guidelines of E.164 but leading 00 is as well accepted
channels	[string]	true	none	Channels selected for delivery.
sms	SMSRequest	false	none	Normal SMS to be sent. If Content is used as well this will override the specification made there. In case URL type is specified the recipient will receive the plain URL as SMS.

SMSRequest

{
  "contentType": "text",
  "from": "1233423454",
  "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
}

Normal SMS to be sent.

If Content is used as well this will override the specification made there.

In case URL type is specified the recipient will receive the plain URL as SMS.

Properties

Name	Type	Required	Restrictions	Description
contentType	string	true	none	What kind of payload should be sent
from	string	false	none	The sender of the message
text	string	false	none	The message to be sent
url	string	false	none	The URL you would like to send. Must be a valid http(s) URL. Note This property will be removed in a future release. Please use `text` instead.

Enumerated values

Property	Value
contentType	text
contentType	url

MessageResponse

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-08-24T14:15:22Z"
}

Properties

Name	Type	Required	Restrictions	Description
messageId	string(uuid)	true	none	Global Message ID reference
acceptedAt	string(date-time)	true	none	Point in time when the API confirms that the message request was accepted

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows the RFC-7807 (https://tools.ietf.org/html/rfc7807)

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference [RFC3986] that identifies the problem type
title	string	true	none	A short, human-readable summary of the problem type.
status	string	true	none	The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail	string	true	none	A human-readable explanation specific to this occurrence of the problem.

MessageRequestContext

{
  "userContext": "my-message-reference"
}

Contextual information for the message request

Properties

Name	Type	Required	Restrictions	Description
userContext	string	false	none	Contextual information that is transfered back on delivery notifications.

MessageRequestOverrides

{
  "notificationCallbackUrl": "https://en4u5fpprib5i.x.pipedream.net"
}

Overrides of defaults for this message

Properties

Name	Type	Required	Restrictions	Description
notificationCallbackUrl	string	false	none	When present this url is used for sending the delivery notifications to your webhook. Can be used for debugging use cases or individual routings.

BulkRequest

{
  "to": "string",
  "from": "string",
  "channel": "sms",
  "sms": [
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    },
    {
      "contentType": "text",
      "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
    }
  ]
}

Bulk request to be sent. The items are guaranted to be sent in order of appearance

Properties

Name	Type	Required	Restrictions	Description
to	string	false	none	none
from	string	false	none	none
channel	string	false	none	Channel which should be used for the bulk
sms	[BulkSMSRequest]	false	none	SMS to be sent

Enumerated values

Property	Value
channel	sms

BulkSMSRequest

{
  "contentType": "text",
  "text": "Thanks for contacting our support. We will get back to you in 5 minutes."
}

Properties

Name	Type	Required	Restrictions	Description
contentType	string	false	none	What kind of payload should be sent
text	string	false	none	The message to be sent

Enumerated values

Property	Value
contentType	text

Webhook Configuration

Version: v2.12

Specification Release Notes Postman Collection Other versions

Base URLs

https://api.tyntec.com/chat-api/v2

Applications

An application allows you to freely define which events should be sent via a callback URL to your webhook implementation. You may use a single callback URL for all event types or separate callback URLs for custom sets of event types.

Important

By now, only a single application (the default application) is supported. The extension to custom applications is planned in future releases.
The API merges events pointing to the same callback URL into one set.
When an update of a callback URL is executed, the whole webhook definition is restated.

The MoMessage::Postback event is treated as a MoMessage event for the purpose of callback lookups.

List all applications

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/applications \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/applications HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/applications',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/applications',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/applications', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/applications', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/applications");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/applications", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /applications

Lists all applications with their webhooks configured for the API key.

Example responses

200 Response

[
  {
    "id": "default",
    "name": "Default Application",
    "webhooks": [
      {
        "events": [
          "MoMessage"
        ],
        "callbackUrl": "https://some-call-back.service.com"
      },
      {
        "events": [
          "MessageStatus::deleted",
          "MessageStatus::accepted"
        ],
        "callbackUrl": "https://some-other-call-back.service.com"
      }
    ]
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	List of applications. Will never be empty.	ApplicationList

Read the default application

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/chat-api/v2/applications/default \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/chat-api/v2/applications/default HTTP/1.1
Host: api.tyntec.com
Accept: application/json
apikey: API_KEY


const headers = {
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/applications/default',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.get 'https://api.tyntec.com/chat-api/v2/applications/default',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'apikey': 'API_KEY'
}

r = requests.get('https://api.tyntec.com/chat-api/v2/applications/default', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Accept' => 'application/json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','https://api.tyntec.com/chat-api/v2/applications/default', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/applications/default");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/chat-api/v2/applications/default", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

GET /applications/default

Returns the default application configured for the API key with details about its webhooks.

Example responses

200 Response

{
  "id": "default",
  "name": "Default Application",
  "webhooks": [
    {
      "events": [
        "MoMessage"
      ],
      "callbackUrl": "https://some-call-back.service.com"
    },
    {
      "events": [
        "MessageStatus::deleted",
        "MessageStatus::accepted"
      ],
      "callbackUrl": "https://some-other-call-back.service.com"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	Current definition of the default application	DefaultApplicationResponse

Update the default application

Code samples

# You can also use wget
curl -X PATCH https://api.tyntec.com/chat-api/v2/applications/default \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

PATCH https://api.tyntec.com/chat-api/v2/applications/default HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

const inputBody = '{
  "webhooks": [
    {
      "events": [
        "MoMessage"
      ],
      "callbackUrl": "https://some-call-back.service.com"
    },
    {
      "events": [
        "MessageStatus::deleted",
        "MessageStatus::accepted"
      ],
      "callbackUrl": "https://some-other-call-back.service.com"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/chat-api/v2/applications/default',
{
  method: 'PATCH',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Content-Type' => 'application/json',
  'Accept' => 'application/problem+json',
  'apikey' => 'API_KEY'
}

result = RestClient.patch 'https://api.tyntec.com/chat-api/v2/applications/default',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/problem+json',
  'apikey': 'API_KEY'
}

r = requests.patch('https://api.tyntec.com/chat-api/v2/applications/default', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/problem+json',
    'apikey' => 'API_KEY',

    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('PATCH','https://api.tyntec.com/chat-api/v2/applications/default', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

URL obj = new URL("https://api.tyntec.com/chat-api/v2/applications/default");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/problem+json");
con.setRequestProperty("apikey", "API_KEY");

int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/problem+json"},
        "apikey": []string{"API_KEY"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api.tyntec.com/chat-api/v2/applications/default", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

PATCH /applications/default

Defines webhooks in the default application by associating specified callback URLs with specified event types. The operation will replace callback URLs on specified event types with the new callback URLs. Omitted event types will remain associated with the previous callback URLs.

Body parameter

{
  "webhooks": [
    {
      "events": [
        "MoMessage"
      ],
      "callbackUrl": "https://some-call-back.service.com"
    },
    {
      "events": [
        "MessageStatus::deleted",
        "MessageStatus::accepted"
      ],
      "callbackUrl": "https://some-other-call-back.service.com"
    }
  ]
}

Parameters

Name	In	Type	Required	Description
body	body	DefaultApplicationUpdate	true	none

Example responses

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.whatsapp.contentType",
      "message": "must not be empty"
    }
  ],
  "title": "Constraint Violation"
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

Responses

Status	Meaning	Description	Schema
204	No Content	Webhooks were saved successfully.	None
400	Bad Request	The request does not match our expectations. Check the Problem object for details.	Problem
default	Default	The default response in the case of any other error. Check the Problem object for details.	Problem

Schemas

EventTypes

"MoMessage"

Determines the event type emitted by the API.

Properties

Name	Type	Required	Restrictions	Description
anonymous	string	false	none	Determines the event type emitted by the API.

Enumerated values

Property	Value
anonymous	MoMessage
anonymous	MessageStatus::accepted
anonymous	MessageStatus::channelFailed
anonymous	MessageStatus::deleted
anonymous	MessageStatus::delivered
anonymous	MessageStatus::failed
anonymous	MessageStatus::seen
anonymous	MessageStatus::unknown

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parsable",
  "status": 400,
  "detail": "Unexpected end-of-input: expected close marker for Object (start marker at [Source: UNKNOWN; line: -1, column: -1) at [Source: UNKNOWN; line: 1, column: 97]\n"
}

The problem object follows RFC 7807.

Properties

Name	Type	Required	Restrictions	Description
type	string	true	none	A URI reference RFC 3986 that identifies the problem type
title	string	true	none	A short, human-readable summary of the problem type.
status	string	true	none	The HTTP status code (RFC 7231, Section 6) generated by the origin server for this occurrence of the problem.
detail	string	true	none	A human-readable explanation specific to this occurrence of the problem.

DefaultApplicationUpdate

{
  "webhooks": [
    {
      "events": [
        "MoMessage"
      ],
      "callbackUrl": "https://some-call-back.service.com"
    },
    {
      "events": [
        "MessageStatus::deleted",
        "MessageStatus::accepted"
      ],
      "callbackUrl": "https://some-other-call-back.service.com"
    }
  ]
}

Update of the default application

Properties

Name	Type	Required	Restrictions	Description
webhooks	[Webhook]	false	none	[A webhook associates one or more event types to a callback URL. In other words, it specifies where the events of those types should be forwarded to. ]

ApplicationList

[
  {
    "id": "default",
    "name": "Default Application",
    "webhooks": [
      {
        "events": [
          "MoMessage"
        ],
        "callbackUrl": "https://some-call-back.service.com"
      },
      {
        "events": [
          "MessageStatus::deleted",
          "MessageStatus::accepted"
        ],
        "callbackUrl": "https://some-other-call-back.service.com"
      }
    ]
  }
]

List of configured applications. It is never empty.

Properties

None

DefaultApplicationResponse

{
  "id": "default",
  "name": "Default Application",
  "webhooks": [
    {
      "events": [
        "MoMessage"
      ],
      "callbackUrl": "https://some-call-back.service.com"
    },
    {
      "events": [
        "MessageStatus::deleted",
        "MessageStatus::accepted"
      ],
      "callbackUrl": "https://some-other-call-back.service.com"
    }
  ]
}

The default application

Properties

Name	Type	Required	Restrictions	Description
id	string	false	none	The default application ID
name	string	false	none	The default application name
webhooks	[Webhook]	false	none	[A webhook associates one or more event types to a callback URL. In other words, it specifies where the events of those types should be forwarded to. ]

Enumerated values

Property	Value
id	default
name	Default Application

Webhook

{
  "events": [
    "MessageStatus::deleted",
    "MessageStatus::accepted"
  ],
  "callbackUrl": "https://some-other-call-back.service.com"
}

A webhook associates one or more event types to a callback URL. In other words, it specifies where the events of those types should be forwarded to.

Properties

Name	Type	Required	Restrictions	Description
events	[EventTypes]	false	none	An array of event types, by which this webhook should be triggered. You may use an empty array to set the default webhook for all event types that aren't assigned specifically. Such webhook will be triggered on every event, for which another webhook doesn't exist that is specific to this event type.
callbackUrl	string	false	none	The URL to forward the event to. Callback URLs should start with `https://`.

Webhook Events

Delivery updates and inbound messages are sent out to you in a manner of events.

They are sent to the callback URLs that you specified in a tyntec application.

Inbound messages are sent to your system as soon as we receive them from the channel.

Delivery updates are sent to your system when:

a message reaches a final state, or
a message reaches an intermediate state and you opted-in to receive this, or
a user decides to delete a message previously sent to you (only available on WhatsApp).

We treat

delivered
seen / read
finally failed

as final states for messages sent by you.

All other states are treated as intermediate states.

Base URLs

production https 78.110.226.11

Server address of tyntec, the events origin from

Received messages

Events emitted when the recipient of the message replies or deletes a previously sent message.

MoMessage (Basic)

Message received by us and delivered to your system via a webhook provided by your system.

Example payload


{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "viber"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which type of event is sent. Always MoMessage
channel	string	true	Channel that triggered the event.
receivedAt	string(date-time)	false	Point in time when the message was received. Note This property will be replaced in the future by the timestamp property from the APIEvent
timestamp	string(date-time)	false	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	true	The sender of the message
to	string	false	Receiver. The format is channel specific
groupId	string	false	Group ID from which the event originates. Only present if the message was sent into a group.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product

Enumerated values

Property	Value
event	MoMessage
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoMessage (SMS)

Message received by us on the SMS channel and delivered to your system via a webhook provided by your system.

Example payload


{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "sms",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  },
  "sms": {
    "origin": {
      "mcc": "string",
      "mnc": "string",
      "ttId": "string"
    },
    "totalPrice": 0,
    "size": 1,
    "missingParts": false,
    "parts": [
      {
        "messageId": "string",
        "sentDate": "2019-03-13T13:15:22Z",
        "price": 0,
        "currency": "string",
        "priceEffective": "2019-03-13T13:15:22Z",
        "sequenceNumber": 1
      }
    ]
  }
}

Properties

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
sms	SMS	false	Details specific to the SMS channel
» origin	SMSOrigin	false	Information about the origin of the message
»» mcc	string	false	A representative MCC (Mobile Network Code) of the originating network.
»» mnc	string	false	A representative MNC (Mobile Network Code) of the originating network.
»» ttId	string	false	The respective tyntec ID of the originating network.
» totalPrice	number	false	The sum of prices for each message part listed in “contentList”.
» size	number	false	The amount of respective concatenated SMS parts.
» missingParts	boolean	false	True in the case a part of an over-length message was not received by the tyntec platform and the forwarded message text is incomplete.
» parts	[SMSContent]	false	tyntec merges over-length (concatenated) SMS into one string before sending it to your webserver. Information for each individual part is collected here
»» messageId	string	false	The unique identifier provided by tyntec for each message part.
»» sentDate	string(date-time)	false	The time stamp when the SMS was received by the sending MSC (if available). or The time stamp when the respective message was received by tyntec.
»» price	number	false	The price per message from the respective network. Negative prices represent payout in favor of tyntec’s customer.
»» currency	string	false	The currency in which the pricing is given; corresponding to the currency of the invoice.
»» priceEffective	string(date-time)	false	The date when the “price” became effective.
»» sequenceNumber	number	false	In the case an over-length message is received tyntec recomposes the full message text before forwarding. The “sequenceNumber” indicates the order of the message part.

Enumerated values

Property	Value
channel	sms

MoMessage (WhatsApp)

Message received by us on the WhatsApp channel and delivered to your system via a webhook provided by your system.

Example payload


{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  },
  "whatsapp": {
    "senderName": "Peter"
  }
}

Properties

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	Whatsapp	false	Details specific to the WhatsApp channel
» senderName	string	false	Name of the sender, set in his or her profile

Enumerated values

Property	Value
channel	whatsapp
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoMessage (Viber)

Message received by us on the Viber channel and delivered to your system via a webhook provided by your system.

Example payload


{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "viber",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  }
}

Properties

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product

Enumerated values

Property	Value
channel	viber
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoMessage Postback

Postbacks are triggered when a user clicks on a button or interacts with any element that supports this. The event is treated as a MoMessage event for the purpose of callback lookups.

Supporting channels

WhatsApp: Quick Reply buttons

Example payload


{
  "event": "MoMessage::PostBack",
  "messageId": "ABGHSRdiRDUxLwIQHWZNgHd-WIdpPHTMERqTgQ",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "postback": {
    "data": "EventVisited::2020-04-04::WhatsAppFair"
  },
  "context": {
    "messageId": "77185196-664a-43ec-b14a-fe97036c697e"
  },
  "whatsapp": {
    "senderName": "open api sample",
    "text": "I liked the event"
  }
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MoMessage::PostBack
channel	string	false	Channel that triggered the event.
timestamp	string(date-time)	true	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	false	The sender of the message
to	string	false	Receiver. The format is channel specific
groupId	string	false	Group ID from which the event originates. Only present if the message was sent into a group
postback	PostBack	false	No description
» data	string	false	Payload or data that was specified when requesting the button based message
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	WhatsAppPostBack	false	Postback data for a WhatsApp quick reply button
» text	string	false	Caption of the button that was clicked
» title	string	false	Title of the interactive item clicked
» description	string	false	Description of the interactive item clicked

Enumerated values

Property	Value
event	MoMessage::Postback
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber

MoMessage Order

Orders are triggered when a user places an order from a pre-filled shopping cart.

The event is treated as a MoMessage event for the purpose of callback lookups.

Supporting channels

WhatsApp: Product and ProductLists

Example payload


{
  "event": "MoMessage::Order",
  "messageId": "ABGHSRdiRDUxLwIQHWZNgHd-WIdpPHTMERqTgQ",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "order": {
    "catalogId": 2378972934234,
    "text": "Please let me know where I can pick up the order.",
    "items": [
      {
        "productId": "24-2597234-sdfk",
        "quantity": 123,
        "itemPrice": 123.22,
        "currency": "EUR"
      },
      {
        "productId": "24-1111134-sdfk",
        "quantity": 1,
        "itemPrice": 1.22,
        "currency": "USD"
      }
    ]
  },
  "whatsapp": {
    "senderName": "Test User"
  }
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MoMessage::Order
channel	string	false	Channel that triggered the event.
timestamp	string(date-time)	true	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	false	The sender of the message
to	string	false	Receiver. The format is channel specific
order	Order	true	Represents an order sent from a channel
» catalogId	string	false	ID of the catalog the items origin from
» text	string	false	Optional message from the customer
» items	[SelectedProduct]	true	Products placed into the basket for this order
»» productId	string	true	ID or SKU of the product selected
»» quantity	string	true	How many items are selected
»» itemPrice	string	false	Price presented to the customer, when chosing the product
»» currency	string	false	Currency of the products price
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	Whatsapp	false	Details specific to the WhatsApp channel
» senderName	string	false	Name of the sender, set in his or her profile

Enumerated values

Property	Value
event	MoMessage::Order
channel	whatsapp

Message Status: Deleted

This event is triggered when a previously sent MoMessage is deleted by its sender.

Supporting channels

Example payload


{
  "event": "MessageStatus::deleted",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "status": "deleted",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "from": 491672634678,
  "to": 4923147790813
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent.
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
status	string	true	Indicates the status of the message. Be aware that not all channels support all statuses. Note This property will be replaced by the property event in a future release.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request
from	string	true	Who triggered this event. Usually the phone number or WhatsApp account ID.
to	string	true	Which channel specific account ID is the recipient of this event.

Enumerated values

Property	Value
event	MessageStatus::deleted
channel	sms
channel	whatsapp
channel	tyntecEcho
status	deleted

Delivery updates

Events emitted on updates of message delivery.

Message Status: Accepted

This event is triggered when tyntec accepted your message request.

This happens after the HTTP status code 202 on a messaging request.

Supporting channels

Example payload


{
  "event": "MessageStatus::accepted",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::accepted
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::accepted
channel	sms
channel	whatsapp
channel	viber

Message Status: Delivered

This event is triggered when the channel informed us about the successful delivery of your message to the recipient.

Supporting channels

WhatsApp
SMS
Viber

Example payload


{
  "event": "MessageStatus::delivered",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::delivered
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::delivered
channel	sms
channel	whatsapp
channel	viber

Message Status: Seen

This event is triggered when the channel informed that the message was seen by the recipient.

Depending on the channel, this is a subject of privacy settings by the recipient, eg. WhatsApp.

Supporting channels

WhatsApp
Viber

Example payload


{
  "event": "MessageStatus::seen",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::seen
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::seen
channel	sms
channel	whatsapp
channel	viber

Message Status: Channel Failed

This event is triggered when a message was not successfully delivered via the channel.

Supporting channels

Example payload


{
  "event": "MessageStatus::channelFailed",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "details": {
    "code": "whatsapp::external::1009",
    "message": "Parameter value is not valid. Button at index 0 of type Url does not require parameters"
  }
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::channelFailed
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request
details	object	false	No description
» code	string	false	Error code to identify the reason
» message	string	false	Additional error message about the error reason

Enumerated values

Property	Value
event	MessageStatus::channelFailed
channel	sms
channel	whatsapp
channel	viber

Message Status: Failed

This event is triggered when the message failed on all configured channels.

Supporting channels

Example payload


{
  "event": "MessageStatus::failed",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::failed
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::failed
channel	sms
channel	whatsapp
channel	viber

Message Status: Unknown

This event is triggered when the message status cannot be mapped to any of the others.

Supporting channels

Example payload


{
  "event": "MessageStatus::unknown",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::unknown
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::unknown
channel	sms
channel	whatsapp
channel	viber

Schemas

APIEvent

{
  "event": "MessageStatus::accepted",
  "channel": "sms",
  "from": 491672634678,
  "timestamp": "2019-06-26T11:41:00"
}

Properties

Abstract event object produced by the API, such as MessageStatus or MoMessage

Name	Type	Required	Description
event	EventTypes	true	Determines the event types emitted by the API
channel	string	false	Channel that triggered the event. Can be empty in case of an internal source
timestamp	string(date-time)	false	Point in time when the event happened
from	string	false	Who triggered this event. Usually a phone number or WhatsApp account ID

Enumerated values

Property	Value
event	MoMessage
event	MoMessage::Postback
event	MessageStatus::accepted
event	MessageStatus::channelFailed
event	MessageStatus::deleted
event	MessageStatus::delivered
event	MessageStatus::failed
event	MessageStatus::seen
event	MessageStatus::unknown
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber

EventTypes

"MoMessage"

Properties

Determines the event types emitted by the API

Name	Type	Required	Description
anonymous	EventTypes	false	Determines the event types emitted by the API

Enumerated values

Property	Value
anonymous	MoMessage
anonymous	MoMessage::Postback
anonymous	MessageStatus::accepted
anonymous	MessageStatus::channelFailed
anonymous	MessageStatus::deleted
anonymous	MessageStatus::delivered
anonymous	MessageStatus::failed
anonymous	MessageStatus::seen
anonymous	MessageStatus::unknown

MoMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "viber"
}

Properties

*Message received by us and delivered to your system via a webhook provided by your system. *

Name	Type	Required	Description
event	string	true	Determines which type of event is sent. Always MoMessage
channel	string	true	Channel that triggered the event.
receivedAt	string(date-time)	false	Point in time when the message was received. Note This property will be replaced in the future by the timestamp property from the APIEvent
timestamp	string(date-time)	false	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	true	The sender of the message
to	string	false	Receiver. The format is channel specific
groupId	string	false	Group ID from which the event originates. Only present if the message was sent into a group.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product

Enumerated values

Property	Value
event	MoMessage
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoContent

{
  "contentType": "media",
  "media": {
    "type": "audio",
    "url": "https://api.tyntec.com/messaging/v1/chat/media/77185196-664a-43ec-b14a-fe97036c697f",
    "mediaId": "77185196-664a-43ec-b14a-fe97036c697f"
  }
}

Properties

Content of the mobile-originated message

Name	Type	Required	Description
contentType	string	true	What kind of payload is used
text	string	false	The received text
media	MoMedia	false	Media information
» type	string	false	What kind of media was received
» url	string	false	The URL of the location where the media is stored
» mediaId	string	false	Plain ID of the media to download
» caption	string	false	Caption specified by the user or the file name of the document

Enumerated values

Property	Value
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoContext

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697a",
  "product": {
    "catalogId": "23343-12342",
    "productId": "123-SKU-12432"
  }
}

Properties

Contextual information of the mobile-originated message

Name	Type	Required	Description
messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
product	Product	false	Product that got a question
» catalogId	string	false	Id of the catalog
» productId	string	false	ID or SKU of the product

Product

{
  "catalogId": "23343-12342",
  "productId": "123-SKU-12432"
}

Properties

Product that got a question

Name	Type	Required	Description
catalogId	string	false	Id of the catalog
productId	string	false	ID or SKU of the product

MoMedia

{
  "type": "audio",
  "url": "https://api.tyntec.com/messaging/v1/chat/media/77185196-664a-43ec-b14a-fe97036c697f",
  "mediaId": "77185196-664a-43ec-b14a-fe97036c697f",
  "caption": "This is an picture of my cat!"
}

Properties

Media information

Name	Type	Required	Description
type	string	false	What kind of media was received
url	string	false	The URL of the location where the media is stored
mediaId	string	false	Plain ID of the media to download
caption	string	false	Caption specified by the user or the file name of the document

Enumerated values

Property	Value
type	image
type	document
type	audio
type	voice
type	video

SMSMoMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "sms",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  },
  "sms": {
    "origin": {
      "mcc": "string",
      "mnc": "string",
      "ttId": "string"
    },
    "totalPrice": 0,
    "size": 1,
    "missingParts": false,
    "parts": [
      {
        "messageId": "string",
        "sentDate": "2019-03-13T13:15:22Z",
        "price": 0,
        "currency": "string",
        "priceEffective": "2019-03-13T13:15:22Z",
        "sequenceNumber": 1
      }
    ]
  }
}

Properties

*Message received by us on the SMS channel and delivered to your system via a webhook provided by your system. *

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
sms	SMS	false	Details specific to the SMS channel
» origin	SMSOrigin	false	Information about the origin of the message
»» mcc	string	false	A representative MCC (Mobile Network Code) of the originating network.
»» mnc	string	false	A representative MNC (Mobile Network Code) of the originating network.
»» ttId	string	false	The respective tyntec ID of the originating network.
» totalPrice	number	false	The sum of prices for each message part listed in “contentList”.
» size	number	false	The amount of respective concatenated SMS parts.
» missingParts	boolean	false	True in the case a part of an over-length message was not received by the tyntec platform and the forwarded message text is incomplete.
» parts	[SMSContent]	false	tyntec merges over-length (concatenated) SMS into one string before sending it to your webserver. Information for each individual part is collected here
»» messageId	string	false	The unique identifier provided by tyntec for each message part.
»» sentDate	string(date-time)	false	The time stamp when the SMS was received by the sending MSC (if available). or The time stamp when the respective message was received by tyntec.
»» price	number	false	The price per message from the respective network. Negative prices represent payout in favor of tyntec’s customer.
»» currency	string	false	The currency in which the pricing is given; corresponding to the currency of the invoice.
»» priceEffective	string(date-time)	false	The date when the “price” became effective.
»» sequenceNumber	number	false	In the case an over-length message is received tyntec recomposes the full message text before forwarding. The “sequenceNumber” indicates the order of the message part.

Enumerated values

Property	Value
channel	sms

SMS

{
  "origin": {
    "mcc": "49",
    "mnc": "176",
    "ttId": "25"
  },
  "totalPrice": 0.1,
  "size": 1,
  "missingParts": false,
  "parts": [
    {
      "messageId": "48514285-4e78-4eef-b0c6-4ce68d40c1c3",
      "sentDate": "2019-03-13T13:15:22Z",
      "price": 0,
      "currency": "EUR",
      "priceEffective": "2019-03-13T13:15:22Z",
      "sequenceNumber": 1
    }
  ]
}

Properties

Details specific to the SMS channel

Name	Type	Required	Description
origin	SMSOrigin	false	Information about the origin of the message
» mcc	string	false	A representative MCC (Mobile Network Code) of the originating network.
» mnc	string	false	A representative MNC (Mobile Network Code) of the originating network.
» ttId	string	false	The respective tyntec ID of the originating network.
totalPrice	number	false	The sum of prices for each message part listed in “contentList”.
size	number	false	The amount of respective concatenated SMS parts.
missingParts	boolean	false	True in the case a part of an over-length message was not received by the tyntec platform and the forwarded message text is incomplete.
parts	[SMSContent]	false	tyntec merges over-length (concatenated) SMS into one string before sending it to your webserver. Information for each individual part is collected here
» messageId	string	false	The unique identifier provided by tyntec for each message part.
» sentDate	string(date-time)	false	The time stamp when the SMS was received by the sending MSC (if available). or The time stamp when the respective message was received by tyntec.
» price	number	false	The price per message from the respective network. Negative prices represent payout in favor of tyntec’s customer.
» currency	string	false	The currency in which the pricing is given; corresponding to the currency of the invoice.
» priceEffective	string(date-time)	false	The date when the “price” became effective.
» sequenceNumber	number	false	In the case an over-length message is received tyntec recomposes the full message text before forwarding. The “sequenceNumber” indicates the order of the message part.

SMSOrigin

{
  "mcc": "49",
  "mnc": "176",
  "ttId": "25"
}

Properties

Information about the origin of the message

Name	Type	Required	Description
mcc	string	false	A representative MCC (Mobile Network Code) of the originating network.
mnc	string	false	A representative MNC (Mobile Network Code) of the originating network.
ttId	string	false	The respective tyntec ID of the originating network.

SMSContent

{
  "messageId": "48514285-4e78-4eef-b0c6-4ce68d40c1c3",
  "sentDate": "2019-08-24T14:15:22Z",
  "price": 0.1,
  "currency": "EUR",
  "priceEffective": "2019-08-24T14:15:22Z",
  "sequenceNumber": 1
}

Properties

SMS channel specific information

Name	Type	Required	Description
messageId	string	false	The unique identifier provided by tyntec for each message part.
sentDate	string(date-time)	false	The time stamp when the SMS was received by the sending MSC (if available). or The time stamp when the respective message was received by tyntec.
price	number	false	The price per message from the respective network. Negative prices represent payout in favor of tyntec’s customer.
currency	string	false	The currency in which the pricing is given; corresponding to the currency of the invoice.
priceEffective	string(date-time)	false	The date when the “price” became effective.
sequenceNumber	number	false	In the case an over-length message is received tyntec recomposes the full message text before forwarding. The “sequenceNumber” indicates the order of the message part.

WhatsAppMoMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  },
  "whatsapp": {
    "senderName": "Peter"
  }
}

Properties

*Message received by us on the WhatsApp channel and delivered to your system via a webhook provided by your system. *

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	Whatsapp	false	Details specific to the WhatsApp channel
» senderName	string	false	Name of the sender, set in his or her profile

Enumerated values

Property	Value
channel	whatsapp
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

{
  "senderName": "Peter"
}

Properties

Details specific to the WhatsApp channel

Name	Type	Required	Description
senderName	string	false	Name of the sender, set in his or her profile

MessageRequestContext

{
  "userContext": "my-message-reference"
}

Properties

Contextual information for the message request

Name	Type	Required	Description
userContext	string	false	Contextual information that is transfered back on delivery notifications.

ViberMoMessage

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697e",
  "event": "MoMessage",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "viber",
  "content": {
    "contentType": "text",
    "text": "Hi, thanks for your support message"
  }
}

Properties

*Message received by us on the Viber channel and delivered to your system via a webhook provided by your system. *

Name	Type	Required	Description
channel	string	true	Channel that triggered the event.
content	MoContent	true	Content of the mobile-originated message
» contentType	string	true	What kind of payload is used
» text	string	false	The received text
» media	MoMedia	false	Media information
»» type	string	false	What kind of media was received
»» url	string	false	The URL of the location where the media is stored
»» mediaId	string	false	Plain ID of the media to download
»» caption	string	false	Caption specified by the user or the file name of the document
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product

Enumerated values

Property	Value
channel	viber
contentType	text
contentType	media
contentType	location
contentType	contacts
type	image
type	document
type	audio
type	voice
type	video

MoMessagePostBack

{
  "event": "MoMessage::PostBack",
  "messageId": "ABGHSRdiRDUxLwIQHWZNgHd-WIdpPHTMERqTgQ",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "postback": {
    "data": "EventVisited::2020-04-04::WhatsAppFair"
  },
  "context": {
    "messageId": "77185196-664a-43ec-b14a-fe97036c697e"
  },
  "whatsapp": {
    "senderName": "open api sample",
    "text": "I liked the event"
  }
}

Properties

*Postbacks are triggered when a user clicks on a button or interacts with any element that supports this.

For WhatsApp only Quick Reply buttons trigger this event. *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MoMessage::PostBack
channel	string	false	Channel that triggered the event.
timestamp	string(date-time)	true	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	false	The sender of the message
to	string	false	Receiver. The format is channel specific
groupId	string	false	Group ID from which the event originates. Only present if the message was sent into a group
postback	PostBack	false	No description
» data	string	false	Payload or data that was specified when requesting the button based message
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	WhatsAppPostBack	false	Postback data for a WhatsApp quick reply button
» text	string	false	Caption of the button that was clicked
» title	string	false	Title of the interactive item clicked
» description	string	false	Description of the interactive item clicked

Enumerated values

Property	Value
event	MoMessage::Postback
channel	sms
channel	whatsapp
channel	tyntecEcho
channel	viber

MoMessageOrder

{
  "event": "MoMessage::Order",
  "messageId": "ABGHSRdiRDUxLwIQHWZNgHd-WIdpPHTMERqTgQ",
  "from": "49123512314",
  "to": "49123512315",
  "timestamp": "2019-06-26T11:41:00",
  "channel": "whatsapp",
  "order": {
    "catalogId": 2378972934234,
    "text": "Please let me know where I can pick up the order.",
    "items": [
      {
        "productId": "24-2597234-sdfk",
        "quantity": 123,
        "itemPrice": 123.22,
        "currency": "EUR"
      },
      {
        "productId": "24-1111134-sdfk",
        "quantity": 1,
        "itemPrice": 1.22,
        "currency": "USD"
      }
    ]
  },
  "whatsapp": {
    "senderName": "Test User"
  }
}

Properties

*Orders are triggered when a user places an order from a shopping cart. *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MoMessage::Order
channel	string	false	Channel that triggered the event.
timestamp	string(date-time)	true	Point in time when the message was received
messageId	string	true	Message ID reference
from	string	false	The sender of the message
to	string	false	Receiver. The format is channel specific
order	Order	true	Represents an order sent from a channel
» catalogId	string	false	ID of the catalog the items origin from
» text	string	false	Optional message from the customer
» items	[SelectedProduct]	true	Products placed into the basket for this order
»» productId	string	true	ID or SKU of the product selected
»» quantity	string	true	How many items are selected
»» itemPrice	string	false	Price presented to the customer, when chosing the product
»» currency	string	false	Currency of the products price
context	MoContext	false	Contextual information of the mobile-originated message
» messageId	string	false	The message ID the MoMessage refers to. Usualy set when the sender replies to a specific message
» product	Product	false	Product that got a question
»» catalogId	string	false	Id of the catalog
»» productId	string	false	ID or SKU of the product
whatsapp	Whatsapp	false	Details specific to the WhatsApp channel
» senderName	string	false	Name of the sender, set in his or her profile

Enumerated values

Property	Value
event	MoMessage::Order
channel	whatsapp

PostBack

{
  "data": "EventVisited::2020-04-04::WhatsAppFair"
}

Properties

Name	Type	Required	Description
data	string	false	Payload or data that was specified when requesting the button based message

WhatsAppPostBack

{
  "text": "Yes",
  "title": "This is the button you clicked",
  "description": "This is the description of a list item",
  "senderName": "Peter"
}

Properties

Postback data for a WhatsApp quick reply button

Name	Type	Required	Description
text	string	false	Caption of the button that was clicked
title	string	false	Title of the interactive item clicked
description	string	false	Description of the interactive item clicked

Order

{
  "catalogId": "123980-12313123",
  "text": "Hi, please make sure you deliver it in the afternoon",
  "items": [
    {
      "productId": "test-sku-1234",
      "quantity": 1,
      "itemPrice": 0.11,
      "currency": "EUR"
    }
  ]
}

Properties

Represents an order sent from a channel

Name	Type	Required	Description
catalogId	string	false	ID of the catalog the items origin from
text	string	false	Optional message from the customer
items	[SelectedProduct]	true	Products placed into the basket for this order
» productId	string	true	ID or SKU of the product selected
» quantity	string	true	How many items are selected
» itemPrice	string	false	Price presented to the customer, when chosing the product
» currency	string	false	Currency of the products price

SelectedProduct

{
  "productId": "test-sku-1234",
  "quantity": 1,
  "itemPrice": 0.11,
  "currency": "EUR"
}

Properties

Product selected for an order

Name	Type	Required	Description
productId	string	true	ID or SKU of the product selected
quantity	string	true	How many items are selected
itemPrice	string	false	Price presented to the customer, when chosing the product
currency	string	false	Currency of the products price

MessageStatusDeleted

{
  "event": "MessageStatus::deleted",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "status": "deleted",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "from": 491672634678,
  "to": 4923147790813
}

Properties

*Indicates that a previously sent inbound MoMessage was deleted by the user. *

Name	Type	Required	Description
event	string	true	Determines which event type is sent.
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
status	string	true	Indicates the status of the message. Be aware that not all channels support all statuses. Note This property will be replaced by the property event in a future release.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request
from	string	true	Who triggered this event. Usually the phone number or WhatsApp account ID.
to	string	true	Which channel specific account ID is the recipient of this event.

Enumerated values

Property	Value
event	MessageStatus::deleted
channel	sms
channel	whatsapp
channel	tyntecEcho
status	deleted

MessageStatusAccepted

{
  "event": "MessageStatus::accepted",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

*Indicates the acceptance of the message by the Conversations API *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::accepted
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::accepted
channel	sms
channel	whatsapp
channel	viber

MessageStatusDelivered

{
  "event": "MessageStatus::delivered",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

*Indicates the delivery of the message to the recipient *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::delivered
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::delivered
channel	sms
channel	whatsapp
channel	viber

MessageStatusSeen

{
  "event": "MessageStatus::seen",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

*Indicates that the message was seen by the recipient *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::seen
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::seen
channel	sms
channel	whatsapp
channel	viber

MessageStatusChannelFailed

{
  "event": "MessageStatus::channelFailed",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z",
  "details": {
    "code": "whatsapp::external::1009",
    "message": "Parameter value is not valid. Button at index 0 of type Url does not require parameters"
  }
}

Properties

*Indicates that the message failed on the particular channel *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::channelFailed
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request
details	object	false	No description
» code	string	false	Error code to identify the reason
» message	string	false	Additional error message about the error reason

Enumerated values

Property	Value
event	MessageStatus::channelFailed
channel	sms
channel	whatsapp
channel	viber

MessageStatusFailed

{
  "event": "MessageStatus::failed",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

*Indicates that all channels failed. *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::failed
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::failed
channel	sms
channel	whatsapp
channel	viber

MessageStatusUnknown

{
  "event": "MessageStatus::unknown",
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "channel": "whatsapp",
  "userContext": "my-message-reference",
  "timestamp": "2019-06-26T11:41:28Z"
}

Properties

*Indicates an unforseen message status. *

Name	Type	Required	Description
event	string	true	Determines which event type is sent. Always MessageStatus::unknown
messageId	string	true	Global Message ID reference
channel	string	true	Channel that triggered the event. Can be empty in case of an internal source.
timestamp	string(date-time)	true	Point in time when the event happened
userContext	string	false	Contextual information set on the message request

Enumerated values

Property	Value
event	MessageStatus::unknown
channel	sms
channel	whatsapp
channel	viber