Code copied successfuly

Conversations API

Version: v3.7

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.

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.

Scope based access control

The Conversations API uses the concept of scopes to control access to different aspects of your Conversations account and channels available to you.

Scopes are divided into two distinct classes read and write.

read grants you read-only access - GET HTTP calls -.

write provides access to data modification or message submission - POST, PATCH, PUT, DELETE HTTP calls -.

Scopes are used on 2 layers, your API key account and the channels available to it.

You can inspect the scopes available to both layers by fetching the information via Configurations.

We reserve the right to revoke any granted scope in case we do detect abusive usage of the API.

Adhered web standards

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

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 list of requested sub-resources
  • previous – The page preceding the current page in the list of requested sub-resources
  • current – The current page in the list of requested sub-resources
  • next – The page following the current page in the list of requested sub-resources
  • last – The last page in the list of requested sub-resources

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

Common operations

Version: v3.0

Specification Release Notes 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 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 (messageStatusUrl) 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 system will fire upon events in the system, in this case upon message status updates.

You may also configure an opt-in filter on one or more MessageStatus::* event types in the Configuration, see Webhook Configuration and Webhook Events V2. The set of available event types slightly varies on each channel:

Channel Accepted Dispatched Delivered Seen Channel failed Deleted
WhatsApp
Viber
SMS

Retries

The tyntec system 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 (inboundMessageUrl) 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 system will fire upon the events of inbound messages.

The events fired upon are of type MoMessage.

Retries

The tyntec system 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 system will keep trying for a maximum of 48 hours.

Base URLs

Message details

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

Check message status

Code samples

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

GET https://api.tyntec.com/conversations/v3/messages/{messageId}/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/conversations/v3/messages/{messageId}/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/conversations/v3/messages/{messageId}/status',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/messages/{messageId}/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/conversations/v3/messages/{messageId}/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/conversations/v3/messages/{messageId}/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/conversations/v3/messages/{messageId}/status", data)
    req.Header = headers

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

GET /messages/{messageId}/status

Check the status of a message

Parameters

Name In Type Required Description
messageId path string(uuid) true The message id provided by tyntec

Example responses

200 Response

{
  "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  "status": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

404 Response

{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404
}

Responses

Status Meaning Description Schema
200 OK The response after the server has accepted the request MessageStatus
404 Not Found The requested element was not found Problem
default Default The default response in case of any other error. Please check the error object for details Problem

List delivery events

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/messages/{messageId}/events \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/messages/{messageId}/events 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/conversations/v3/messages/{messageId}/events',
{
  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/conversations/v3/messages/{messageId}/events',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/messages/{messageId}/events', 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/conversations/v3/messages/{messageId}/events', 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/conversations/v3/messages/{messageId}/events");
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/conversations/v3/messages/{messageId}/events", data)
    req.Header = headers

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

GET /messages/{messageId}/events

List the delivery events of a message

Parameters

Name In Type Required Description
messageId path string(uuid) true The message id provided by tyntec

Example responses

200 Response

{
  "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  "events": [
    {
      "timestamp": "2021-11-19T06:39:28.081Z",
      "event": "MessageStatus::channelFailed",
      "channel": "whatsapp",
      "details": {
        "code": "whatsapp::error::470",
        "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
      }
    }
  ]
}

404 Response

{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404
}

Responses

Status Meaning Description Schema
200 OK The list of delivery events MessageDeliveryEvents
404 Not Found The requested element was not found Problem
default Default The default response in case of any other error. Please check the error 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 media file

Code samples

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

GET https://api.tyntec.com/conversations/v3/media/{mediaId} HTTP/1.1
Host: api.tyntec.com
Accept: audio/*
apikey: API_KEY


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

};

fetch('https://api.tyntec.com/conversations/v3/media/{mediaId}',
{
  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/conversations/v3/media/{mediaId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/media/{mediaId}', 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/conversations/v3/media/{mediaId}', 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/conversations/v3/media/{mediaId}");
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/conversations/v3/media/{mediaId}", data)
    req.Header = headers

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

GET /media/{mediaId}

Retrieve the media associated with the id

Parameters

Name In Type Required Description
mediaId path string(uuid) true Media ID provided by tyntec

Example responses

200 Response

404 Response

{
  "status": 404
}

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 media associated with the id requested exists. string
404 Not Found The media associated with the id does not exist in our system Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Outbound media (Beta)

As an alternative to the download of outbound media on message requests, we enable you to upload a media file and use it later when sending messages.

After a successful upload, we generate an ID that is used as an alternative to the media URL.

The uploaded media can be stored

  • as a static asset
  • only for a certain period
  • for one-time usage

As this is in beta, we grant access to it only via an approved access request.

List uploaded media files

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/media \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/media 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/conversations/v3/media',
{
  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/conversations/v3/media',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/media', 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/conversations/v3/media', 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/conversations/v3/media");
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/conversations/v3/media", data)
    req.Header = headers

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

GET /media

Lists all uploaded media files

Example responses

200 Response

[
  {
    "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
    "contentType": "string",
    "validity": "2019-08-24T14:15:22Z",
    "fileName": "string",
    "fileSize": 0
  }
]

Responses

Status Meaning Description Schema
200 OK list of stored media files Inline
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [MediaResponse] false none none
» mediaId string(uuid) false none The media ID provided by tyntec
» contentType string false none The media type
» validity string(date-time) false none For how long is the media stored in minutes
» fileName string false none The name of the file
» fileSize integer false none The size of the file in bytes

Upload a media file

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/media \
  -H 'Content-Type: */*' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/media HTTP/1.1
Host: api.tyntec.com
Content-Type: */*
Accept: application/json
apikey: API_KEY

const inputBody = 'string';
const headers = {
  'Content-Type':'*/*',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/media',
{
  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' => '*/*',
  'Accept' => 'application/json',
  'apikey' => 'API_KEY'
}

result = RestClient.post 'https://api.tyntec.com/conversations/v3/media',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/v3/media', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

$headers = array(
    'Content-Type' => '*/*',
    '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/conversations/v3/media', 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/conversations/v3/media");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "*/*");
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{"*/*"},
        "Accept": []string{"application/json"},
        "apikey": []string{"API_KEY"},

    }

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

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

POST /media

Uploads a media file for message sending

Body parameter

Parameters

Name In Type Required Description
validity query integer false For how long is the media stored in minutes.
filename query string false the name of the file
body body string(binary) true the media to be uploaded

Example responses

200 Response

{
  "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
  "url": "string",
  "quota": 0,
  "usage": 0
}

Responses

Status Meaning Description Schema
200 OK The media was successfully uploaded MediaUploadResponse
default Default The default response in case of any other error. Please check the error object for details Problem

Delete a media file

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/v3/media/{mediaId} \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

DELETE https://api.tyntec.com/conversations/v3/media/{mediaId} 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/conversations/v3/media/{mediaId}',
{
  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/conversations/v3/media/{mediaId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/v3/media/{mediaId}', 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/conversations/v3/media/{mediaId}', 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/conversations/v3/media/{mediaId}");
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/conversations/v3/media/{mediaId}", data)
    req.Header = headers

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

DELETE /media/{mediaId}

Deletes a prior uploaded media.

Parameters

Name In Type Required Description
mediaId path string(uuid) true Media ID provided by tyntec

Example responses

default Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 The associated media was successfully deleted None
default Default The default response in case of any other error. Please check the error object for details Problem

Schemas

MessageRequest

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "whatsapp",
  "content": {
    "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 message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
overrides MessageRequestOverrides false none Overrides of defaults for this message
context string false none The context for this particular message
content object false none The message's content. Refer to the channel specifics
Enumerated values
Property Value
channel sms
channel whatsapp
channel viber

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.

MessageResponse

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

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none A global unique Message Id reference
timestamp string(date-time) true none A point in time when the API confirms that the message request was accepted

MessageStatus

{
  "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  "status": "string",
  "timestamp": "2019-08-24T14:15:22Z"
}

Properties

Name Type Required Restrictions Description
messageId string(uuid) false none Global unique Message Id reference
status string false none Current status of the message
timestamp string(date-time) false none Point in time when status has been entered

MessageDeliveryEvents

{
  "messageId": "8540d774-4863-4d2b-b788-4ecb19412e85",
  "events": [
    {
      "timestamp": "2021-11-19T06:39:28.081Z",
      "event": "MessageStatus::channelFailed",
      "channel": "whatsapp",
      "details": {
        "code": "whatsapp::error::470",
        "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
      }
    }
  ]
}

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none Global unique Message Id reference
events [MessageDeliveryEvent] true none none

MessageDeliveryEvent

{
  "timestamp": "2021-11-19T06:39:28.081Z",
  "event": "MessageStatus::channelFailed",
  "channel": "whatsapp",
  "details": {
    "code": "whatsapp::error::470",
    "message": "Message failed to send because more than 24 hours have passed since the customer last replied to this number"
  }
}

Properties

Name Type Required Restrictions Description
timestamp string(date-time) true none Point in time when the event has happened.
event string true none Determines which kind of event has happened.
channel string false none Channel selected for delivery.
details object false none Channel specific details.
» code string true none none
» message string true none none
Enumerated values
Property Value
channel sms
channel whatsapp
channel viber

BulkMessageRequest

{}

Properties

None

BulkMessageResponse

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

Properties

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

MediaUploadResponse

{
  "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
  "url": "string",
  "quota": 0,
  "usage": 0
}

Properties

Name Type Required Restrictions Description
mediaId string(uuid) true none none
url string true none none
quota integer true none none
usage integer true none none

MediaResponse

{
  "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
  "contentType": "string",
  "validity": "2019-08-24T14:15:22Z",
  "fileName": "string",
  "fileSize": 0
}

Properties

Name Type Required Restrictions Description
mediaId string(uuid) false none The media ID provided by tyntec
contentType string false none The media type
validity string(date-time) false none For how long is the media stored in minutes
fileName string false none The name of the file
fileSize integer false none The size of the file in bytes

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

WhatsApp

Version: v3.19

Specification Release Notes Other versions

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

Channel specific pre-conditions

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

Product & Product Lists (beta)

The support for product and product lists is currently in beta status on our API.

Please contact us via WhatsApp or support@tyntec.com

Base URLs

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/conversations/v3/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

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

const inputBody = '{
  "from": "a cool business",
  "to": "some number",
  "channel": "whatsapp",
  "content": {
    "contentType": "text",
    "text": "hi there"
  },
  "context": "my-message-reference"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/messages", data)
    req.Header = headers

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

POST /messages

Send messages via this path.

Body parameter

{
  "from": "a cool business",
  "to": "some number",
  "channel": "whatsapp",
  "content": {
    "contentType": "text",
    "text": "hi there"
  },
  "context": "my-message-reference"
}

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",
  "timestamp": "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 response after the server has accepted the request 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 The default response in case of any other error. Please check the error object for details Problem

Send a bulk message

Code samples

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

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

const inputBody = '{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "whatsapp",
  "messages": [
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    },
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/bulks", data)
    req.Header = headers

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

POST /bulks

Send bulk messages. Bulk messages are defined as ordered messages to one receiver.

Body parameter

{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "whatsapp",
  "messages": [
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    },
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    }
  ]
}

Parameters

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

Example responses

202 Response

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

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 response after the server has accepted the request BulkMessageResponse
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 The default response in case of any other error. Please check the error object for details Problem

Mark a message as read

Code samples

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

PUT https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 parseable",
  "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 was found for the given Message ID. Problem
default Default The default response in case of any other error. Please check the error 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 subresources of a WhatsApp account can only be managed by API accounts with the respective scopes.

Manageable subresources are:

  • templates

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/conversations/v3/channels/whatsapp/accounts \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 The 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 The default response in case of any other error. Please check the error object for details Problem

Response Headers

Status Header Type Format 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 The 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 The default response in case of any other error. Please check the error object for details Problem

List phone numbers

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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": "49123456789",
    "displayPhoneNumber": "+49 123 45678",
    "verifiedName": "Swagger Sample",
    "qualityRating": "YELLOW",
    "status": "FLAGGED",
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "managedBy": {
      "accountName": "tyntecscpaas"
    },
    "messagingVia": {
      "accountName": "messagingcpaas"
    },
    "nameStatus": "APPROVED",
    "isOfficialBusinessAccount": false
  }
]

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 The default response in case of any other error. Please check the error object for details Problem

Response Headers

Status Header Type Format 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 The 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.

You can specify examples for the parameters of each localization. This is advised to increase the chance of acceptance of templates. If you use examples, all dynamic parts of the template, like media header or body parameters, must be specified.

It's advised to do this at least for the media templates, as WhatsApp has changed the policies due to abuse of media headers to distribute spam / inappropriate content.

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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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",
    "templateName": "swagger_test",
    "category": "MARKETING",
    "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 The default response in case of any other error. Please check the error object for details Problem

Response Headers

Status Header Type Format 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 The 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/conversations/v3/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/conversations/v3/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": "UTILITY",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}},\n\nWelcome to 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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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": "UTILITY",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "Hi {{1}},\n\nWelcome to 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 parseable",
  "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. Please check the Problems object for details Problem
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Response Headers

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

Read a template

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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",
  "templateName": "swagger_test",
  "category": "MARKETING",
  "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 The default response in case of any other error. Please check the error object for details Problem

Delete a template

Code samples

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

DELETE https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 parseable",
  "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 The default response in case of any other error. Please check the error object for details Problem

List localizations

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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."
      ]
    },
    "messageSendTimeToLiveSeconds": 120
  }
]

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 The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

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

anyOf

Name Type Required Restrictions Description
»» anonymous WhatsAppTemplateHeaderComponentResponse false none A header component of a template
»»» type string true none A component type
»»» format string true none What kind of header
»»» text string false none The textual part in the case the format is TEXT

or

Name Type Required Restrictions Description
»» anonymous WhatsAppTemplateBodyComponentResponse false none A body component of a template
»»» type string true none A component type
»»» text string true none The specification of the body text

or

Name Type Required Restrictions Description
»» anonymous WhatsAppTemplateFooterComponentResponse false none A footer component of a template
»»» type string true none A component type
»»» text string false none The 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 the localization expires.
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 A textual description of why the quality score is set to the value.
Only present when the score is YELLOW or RED
» messageSendTimeToLiveSeconds integer false none If WhatsApp is unable to deliver a message to a user, we will continue attempting to deliver the message for a period of time known as a time-to-live. Newly created authentication templates have a default time-to-live of 10 minutes. Possible values for an authentication template is value between 60 and 600 seconds. Additionally, -1 is set time-to-live for message default value (24 hours Cloud API or 30 days for On-Premises API).
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 ka
language kk
language kn
language ko
language ky_KG
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 rw_RW
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/conversations/v3/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/conversations/v3/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"
    }
  ],
  "messageSendTimeToLiveSeconds": 60
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/problem+json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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"
    }
  ],
  "messageSendTimeToLiveSeconds": 60
}

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 parseable",
  "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. Please check the Problems object for details Problem
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Response Headers

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

Edit template

Code samples

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

PATCH https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/problem+json
apikey: API_KEY

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

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}',
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}", data)
    req.Header = headers

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

PATCH /channels/whatsapp/accounts/{whatsapp-account-id}/templates/{template-id}/{template-language}

Edit a template in a specific language.

Body parameter

{
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "string"
    }
  ]
}

Parameters

Name In Type Required Description
body body TemplatePatchRequest true The template patch request. Exactly one out of category and components must be present.
whatsapp-account-id path string true WhatsApp account ID
template-id path string true Referenced template
template-language path string true Template localizations language code
Detailed description

body: The template patch request. Exactly one out of category and components must be present.

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 parseable",
  "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 OK. None
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

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/conversations/v3/channels/whatsapp/phone-numbers \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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": "49123456789",
    "displayPhoneNumber": "+49 123 45678",
    "verifiedName": "Swagger Sample",
    "qualityRating": "YELLOW",
    "status": "FLAGGED",
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "managedBy": {
      "accountName": "tyntecscpaas"
    },
    "messagingVia": {
      "accountName": "messagingcpaas"
    },
    "nameStatus": "APPROVED",
    "isOfficialBusinessAccount": false
  }
]

Responses

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

Response Headers

Status Header Type Format 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 The 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 The phone number used for WhatsApp messaging

Example responses

200 Response

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

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 The default response in case of any other error. Please check the error object for details Problem

List available templates

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 The phone number used for WhatsApp messaging

Example responses

200 Response

[
  {
    "whatsAppAccountId": "5637b8a7-51e1-47be-ad0b-b242453dcc1b",
    "templateName": "swagger_test",
    "category": "MARKETING",
    "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 The default response in case of any other error. Please check the error object for details Problem

Response Headers

Status Header Type Format 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 The 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 the profile settings of your WhatsApp phone numbers.

Read the profile

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 the profile settings of a WhatsApp phone number

Parameters

Name In Type Required Description
phone-number path integer true The 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 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 The default response in case of any other error. Please check the error object for details Problem

Update the profile

Code samples

# You can also use wget
curl -X PATCH https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 Updated profile settings
phone-number path integer true The 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 parseable",
  "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 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 The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 400

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

Code samples

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

GET https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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
format query string false The format in which the icon should be returned. The default is binary.
phone-number path integer true The phone number used for WhatsApp messaging
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 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 The default response in case of any other error. Please check the error object for details Problem

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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 The image that should be used as the profile logo
phone-number path integer true The phone number used for WhatsApp messaging

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 parseable",
  "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. Please check the Problems object for details Problem
403 Forbidden You 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 The default response in case of any other error. Please check the error object for details Problem

Get commerce icons setting

Code samples

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

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce',
{
  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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce', 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce', 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce");
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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce", data)
    req.Header = headers

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

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

Parameters

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

Example responses

200 Response

{
  "enabled": true
}

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 commerce setting WhatsAppCommerceSettings
403 Forbidden You 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 The default response in case of any other error. Please check the error object for details Problem

Set commerce icons setting

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce?enable=true \
  -H 'Accept: application/problem+json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce?enable=true 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce?enable=true',
{
  method: 'POST',

  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.post 'https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce',
  params: {
  'enable' => 'boolean'
}, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce', params={
  'enable': 'true'
}, 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('POST','https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce', 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/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce?enable=true");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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("POST", "https://api.tyntec.com/conversations/v3/channels/whatsapp/phone-numbers/{phone-number}/settings/commerce", data)
    req.Header = headers

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

POST /channels/whatsapp/phone-numbers/{phone-number}/settings/commerce

Parameters

Name In Type Required Description
enable query boolean true none
phone-number path integer true The phone number used for WhatsApp messaging

Example responses

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 parseable",
  "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 commerce setting successfully set None
403 Forbidden You 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 The default response in case of any other error. Please check the error object for details Problem

Phone Number Configurations

List all phone numbers configured as Inbound (aka 2-way) Phone Numbers.

List Configurations

Code samples

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

GET https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp 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/conversations/v3/configurations/channels/whatsapp',
{
  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/conversations/v3/configurations/channels/whatsapp',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp', 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/conversations/v3/configurations/channels/whatsapp', 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/conversations/v3/configurations/channels/whatsapp");
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/conversations/v3/configurations/channels/whatsapp", data)
    req.Header = headers

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

GET /configurations/channels/whatsapp

List all WhatsApp phone number configurations available to your API account

Example responses

200 Response

[
  {
    "channel": "whatsapp",
    "scopes": [
      "messages:read",
      "profile:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

403 Response

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

Responses

Status Meaning Description Schema
200 OK A list of WhatsApp phone number configurations WhatsAppChannelResponses
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Read one configuration

Code samples

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

GET https://api.tyntec.com/conversations/v3/configurations/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/conversations/v3/configurations/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/conversations/v3/configurations/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/conversations/v3/configurations/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/conversations/v3/configurations/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/conversations/v3/configurations/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/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}", data)
    req.Header = headers

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

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

Returns the specific configuration

Parameters

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

Example responses

200 Response

{
  "channel": "whatsapp",
  "scopes": [
    "messages:read",
    "profile:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

403 Response

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

Responses

Status Meaning Description Schema
200 OK The WhatsApp phone number configuration WhatsAppChannelResponse
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Callback configuration

In this section, we guide you on how to configure the callbacks on a per-channel basis.

Update the callback

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks', 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/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks", data)
    req.Header = headers

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

PUT /configurations/channels/whatsapp/phone-numbers/{phone-number}/callbacks

Update the callback settings of a specific phone number.

Body parameter

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

Parameters

Name In Type Required Description
body body ChannelCallback false none
phone-number path integer true The phone number used for WhatsApp messaging

Example responses

200 Response

{
  "channel": "whatsapp",
  "scopes": [
    "messages:read",
    "profile:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

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
200 OK The WhatsApp phone number configuration WhatsAppChannelResponse
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 The default response in case of any other error. Please check the error object for details Problem

Flows management

Flows management enables you to interact with the flows defined for your WhatsApp account. The Flows API enables you to perform a variety of operations with Flows, like create flows, update flows, get flows, publish...

List flows

Code samples

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

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows", data)
    req.Header = headers

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

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

Lists all flows of your WhatsApp account, including flows in draft and deprecated state

Parameters

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

Example responses

200 Response

[
  {
    "id": 12345678901234,
    "name": "Flow test",
    "status": "DRAFT",
    "categories": [
      "OTHER"
    ],
    "validationErrors": []
  }
]

404 Response

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

Responses

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

Create basic flow data

Code samples

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

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows',
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows", data)
    req.Header = headers

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

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

Body parameter

{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}

Parameters

Name In Type Required Description
body body CreateFlowRequest true The flow basic data you would like to create
whatsapp-account-id path string true WhatsApp account ID

Example responses

201 Response

{
  "flowId": 1234567890123456
}

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": "WhatsApp account unknown"
}

Responses

Status Meaning Description Schema
201 Created The WhatsApp phone number configuration CreateFlow
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
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Flow details

Code samples

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

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}", data)
    req.Header = headers

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

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

This request will return a single Flow's details.

Parameters

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

Example responses

200 Response

{
  "id": 1234567890123456,
  "name": "Test flow",
  "status": "DRAFT",
  "categories": [
    "SIGN_UP",
    "OTHER"
  ],
  "validationErrors": {
    "error": "INVALID_PROPERTY",
    "errorType": "JSON_SCHEMA_ERROR",
    "message": "The property 'initial-text' cannot be specified",
    "lineStart": 46,
    "lineEnd": 46,
    "columnStart": 17,
    "columnEnd": 30
  },
  "jsonVersion": 3,
  "dataApiVersion": 3,
  "endpointUri": "Test flow",
  "preview": {
    "previewUrl": "https://previewLink.com/flows/1234567890123/preview/?token=bf747eb7",
    "expiresAt": "2024-02-21T15:15:32+0000"
  }
}

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"
}

Responses

Status Meaning Description Schema
200 OK Returned the flow WhatsAppFlowDetail
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Updating Flow's Metadata

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}',
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}", data)
    req.Header = headers

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

POST /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}

Body parameter

{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}

Parameters

Name In Type Required Description
body body UpdateFlowRequest true After you have created your Flow, you can update the name or categories using the update request.
whatsapp-account-id path string true WhatsApp account ID
whatsapp-flow-id path string true WhatsApp flow ID

Example responses

200 Response

{
  "success": true
}

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": "WhatsApp account unknown"
}

Responses

Status Meaning Description Schema
200 OK Successfully updated flow info 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
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none

Delete flow

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

DELETE https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.delete 'https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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('DELETE','https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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("DELETE", "https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}", data)
    req.Header = headers

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

DELETE /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}

Flow can be deleted just when it is in draft state.

Parameters

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

Example responses

200 Response

{
  "success": true
}

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"
}

Responses

Status Meaning Description Schema
200 OK Successfully deleted flow Inline
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none

Get assets of the flow

Code samples

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

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets", data)
    req.Header = headers

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

GET /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets

This request will return list of assets (json) attached to the flow

Parameters

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

Example responses

200 Response

[
  {
    "name": "flow.json",
    "assetType": "FLOW_JSON",
    "downloadUrl": "https://scontent.xx.fbcdn.net/m1/v/test"
  }
]

404 Response

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

Responses

Status Meaning Description Schema
200 OK Returned the asset list WhatsAppFlowAssets
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

To update Flow JSON for a specified Flow, use this request. Add file as application/json. Do not use form-data.

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "file": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets',
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets", data)
    req.Header = headers

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

POST /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/assets

Body parameter

{
  "file": "string"
}

Parameters

Name In Type Required Description
body body object true Add file as application/json. Do not use form-data.
» file body string(binary) false none
whatsapp-account-id path string true WhatsApp account ID
whatsapp-flow-id path string true WhatsApp flow ID

Example responses

200 Response

{
  "success": true,
  "validationErrors": [
    {
      "error": "INVALID_PROPERTY",
      "errorType": "JSON_SCHEMA_ERROR",
      "message": "The property 'initial-text' cannot be specified",
      "lineStart": 46,
      "lineEnd": 46,
      "columnStart": 17,
      "columnEnd": 30
    }
  ]
}

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": "WhatsApp account unknown"
}

Responses

Status Meaning Description Schema
200 OK Successfully add json asset 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
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none
» validationErrors [FlowValidationError] false none The list of asset validation errors. List is empty if the asset has no errors.
»» error string false none Error name of the flow
»» errorType string false none Type of the error
»» message string false none Error message
»» lineStart string false none The line where error starts, in json flow
»» lineEnd string false none The line where error ends, in json flow
»» columnStart string false none The column where error starts, in json flow
»» columnEnd string false none The column where error ends, in json flow

Code samples

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

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview',
{
  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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview");
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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview", data)
    req.Header = headers

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

GET /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/preview

In order to visualize the Flows created, you can generate a web preview URL with this request. The preview URL is public and can be shared with different stakeholders to visualize the Flow.

Parameters

Name In Type Required Description
whatsapp-account-id path string true WhatsApp account ID
whatsapp-flow-id path string true WhatsApp flow ID
invalidate query boolean false If invalidate is set to true, a new link will be generated, with new expire date. Otherwise, same one will be used. Default value is false.

Example responses

200 Response

{
  "previewUrl": "https://previewLink.com/flows/1234567890123/preview/?token=bf747eb7",
  "expiresAt": "2024-02-21T15:15:32+0000"
}

404 Response

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

Responses

Status Meaning Description Schema
200 OK Returned the preview link and expire date WhatsAppFlowPreview
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem

This request updates the status of the Flow to "PUBLISHED". This action is not reversible. The Flow and its assets become immutable once published.

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish',
{
  method: 'POST',

  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.post 'https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish', 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('POST','https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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("POST", "https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish", data)
    req.Header = headers

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

POST /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/publish

Parameters

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

Example responses

200 Response

{
  "success": true
}

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": "WhatsApp account unknown"
}

Responses

Status Meaning Description Schema
200 OK Successfully published flow 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
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none

Once a Flow is published, it cannot be modified or deleted, but can be marked as deprecated.

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate',
{
  method: 'POST',

  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.post 'https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate', 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('POST','https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate', 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/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
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("POST", "https://api.tyntec.com/conversations/v3/channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate", data)
    req.Header = headers

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

POST /channels/whatsapp/accounts/{whatsapp-account-id}/flows/{whatsapp-flow-id}/deprecate

Parameters

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

Example responses

200 Response

{
  "success": true
}

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": "WhatsApp account unknown"
}

Responses

Status Meaning Description Schema
200 OK Successfully deprecated flow 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
404 Not Found The WhatsApp account does not exist. Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
» success boolean false none none

Schemas

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

MessageResponse

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

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none A global unique Message Id reference
timestamp string(date-time) true none A point in time when the API confirms that the message request was accepted

BulkMessageResponse

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

Properties

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

MessageRequest

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "whatsapp",
  "content": {
    "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 message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
context string false none The context for this particular message
content any false none none

oneOf

Name Type Required Restrictions Description
» anonymous WhatsAppTextContent false none A plain text message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppImageContent false none Image message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppDocumentContent false none A document message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppVideoContent false none A video message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppAudioContent false none An audio message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppStickerContent false none A sticker message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppLocationContent false none A location message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppReactionContent false none A reaction message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppContactsContent false none A message with contacts

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateContent false none Templated message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveContent false none Interactive message
Enumerated values
Property Value
channel whatsapp

BulkMessageRequest

{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "whatsapp",
  "messages": [
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    },
    {
      "contentType": "text",
      "text": "string",
      "renderUrlPreview": false
    }
  ]
}

The bulk of messages you would like to send

Properties

Name Type Required Restrictions Description
to string true none The message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
messages [oneOf] true none none

oneOf

Name Type Required Restrictions Description
» anonymous WhatsAppTextContent false none A plain text message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppImageContent false none Image message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppDocumentContent false none A document message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppVideoContent false none A video message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppAudioContent false none An audio message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppStickerContent false none A sticker message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppLocationContent false none A location message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppContactsContent false none A message with contacts

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateContent false none Templated message
Enumerated values
Property Value
channel whatsapp

CreateFlowRequest

{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}

The flow data you would like to create

Properties

Name Type Required Restrictions Description
name string true none Flow name
categories [FlowCategory] true none A list of Flow categories. Flow must have at least one category

UpdateFlowRequest

{
  "name": "Test flow",
  "categories": [
    "OTHER"
  ]
}

Flow data you would like to change

Properties

Name Type Required Restrictions Description
name string false none Flow name
categories [FlowCategory] false none A list of Flow categories. Flow must have at least one category

WhatsAppTextContent

{
  "contentType": "text",
  "text": "string",
  "renderUrlPreview": false
}

A plain text message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always text.
text string true none Text to be sent
renderUrlPreview boolean false none In case a URL is present on the text should a preview be tried to be rendered
Enumerated values
Property Value
contentType text

WhatsAppImageContent

{
  "contentType": "image",
  "image": {
    "caption": "string",
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Image message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always image.
image WhatsAppImage true none An image media specification
Enumerated values
Property Value
contentType image

WhatsAppDocumentContent

{
  "contentType": "document",
  "document": {
    "caption": "string",
    "filename": "string",
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

A document message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always document.
document WhatsAppDocument true none A document media specification
Enumerated values
Property Value
contentType document

WhatsAppVideoContent

{
  "contentType": "video",
  "video": {
    "caption": "string",
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

A video message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always video.
video WhatsAppVideo true none A video media specification
Enumerated values
Property Value
contentType video

WhatsAppAudioContent

{
  "contentType": "audio",
  "audio": {
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

An audio message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always audio.
audio WhatsAppAudio true none An audio media specification
Enumerated values
Property Value
contentType audio

WhatsAppStickerContent

{
  "contentType": "sticker",
  "sticker": {
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

A sticker message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always sticker.
sticker WhatsAppSticker true none A sticker media specification
Enumerated values
Property Value
contentType sticker

WhatsAppLocationContent

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

A location message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always location.
location WhatsAppLocation true none Location received or send
Enumerated values
Property Value
contentType location

WhatsAppReactionContent

{
  "contentType": "reaction",
  "reaction": {
    "messageId": "wamid.j0nmfofmneofn30fnekn2929",
    "emoji": "😀"
  }
}

A reaction message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always reaction.
reaction WhatsAppReaction true none An emoji reaction to a formerly sent or received message
Enumerated values
Property Value
contentType reaction

WhatsAppContactsContent

{
  "contentType": "contacts",
  "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"
        }
      ]
    }
  ]
}

A message with contacts

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always contacts.
contacts [Contact] true none [A contact object]
Enumerated values
Property Value
contentType contacts

WhatsAppTemplateContent

{
  "contentType": "template",
  "template": {
    "templateId": "string",
    "templateLanguage": "string",
    "components": {
      "header": [
        {
          "type": "text",
          "text": "string",
          "example": {
            "text": "John Doe"
          }
        }
      ],
      "body": [
        {
          "type": "text",
          "text": "string",
          "example": {
            "texts": [
              "John Doe",
              "Order ID 123"
            ]
          }
        }
      ],
      "button": [
        {
          "type": "quick_reply",
          "index": 0,
          "payload": "string"
        }
      ],
      "carousel": {
        "cardIndex": 0,
        "components": {
          "header": [
            {
              "type": "image",
              "image": {
                "url": "string",
                "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
              }
            }
          ],
          "body": [
            {
              "type": "text",
              "text": "string",
              "example": {
                "texts": [
                  "John Doe",
                  "Order ID 123"
                ]
              }
            }
          ],
          "button": {
            "type": "quick_reply",
            "index": 0,
            "payload": "string"
          }
        }
      }
    }
  }
}

Templated message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always template.
template WhatsAppTemplate true none none
Enumerated values
Property Value
contentType template

WhatsAppInteractiveContent

{
  "contentType": "interactive",
  "interactive": {
    "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

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always interactive.
interactive any true none none

oneOf

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

xor

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

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveProductMessage false none Interactive Product Message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveProductListMessage false none Interactive Product List Message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveLocationMessage false none Interactive Location Message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveFlowMessage false none Interactive Flow Message

xor

Name Type Required Restrictions Description
» anonymous WhatsAppInteractiveAddressMessage false none Interactive Address Message. Only available in India and Singapore
Enumerated values
Property Value
contentType interactive

WhatsAppInteractiveFooterContent

{
  "type": "text",
  "text": "string"
}

The footer of an interactive message

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the message. Always text.
text string true none A footer to be displayed on the message
Enumerated values
Property Value
type text

WhatsAppInteractiveTextContent

{
  "type": "text",
  "text": "string"
}

The message body of an interactive message

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the message. Always text.
text string true none The text body of the message
Enumerated values
Property Value
type text

BaseMedia

{
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

A base object handling media definitions for sending.

One of both properties url or id must be set

Properties

Name Type Required Restrictions Description
url string false none The URL of the location where the media is stored
id string(uuid) false none The media id of previously uploaded media

WhatsAppImage

{
  "caption": "string",
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

An image media specification

Properties

Name Type Required Restrictions Description
caption string false none none

WhatsAppDocument

{
  "caption": "string",
  "filename": "string",
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

A document media specification

Properties

Name Type Required Restrictions Description
caption string false none none
filename string false none none

WhatsAppVideo

{
  "caption": "string",
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

A video media specification

Properties

Name Type Required Restrictions Description
caption string false none none

WhatsAppAudio

{
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

An audio media specification

Properties

None

WhatsAppSticker

{
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

A sticker media specification

Properties

None

WhatsAppLocation

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

Location received or send

Properties

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

WhatsAppReaction

{
  "messageId": "wamid.j0nmfofmneofn30fnekn2929",
  "emoji": "😀"
}

An emoji reaction to a formerly sent or received message

Properties

Name Type Required Restrictions Description
messageId string true none The message id of the message you want to react to.
emoji string true none The actual reaction emoji. Must be a string consisting of exactly one emoji or an empty string to delete a former reaction.

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"
    }
  ]
}

A contact object

Properties

Name Type Required Restrictions Description
birthday string false none The birthday of the contact
addresses [Address] false none A list of addresses assigned to the contact
emails [Email] false none A list of emails assigned to the contact
ims [IMS] false none A list of IMS accounts assigned to the contact
name Name false none The name of a contact. Apart from the property formattedName at least one of the other must be set
org Organisation false none An organisation associated with the contact
phones [ContactPhone] false none A list of phone numbers assigned to the contact
urls [ContactUrl] false none A list of URLs assigned to the contact

Address

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

An address of a contact

Properties

Name Type Required Restrictions Description
city string false none The city name
country string false none The full country name
countryCode string false none The two-letter code abbreviation
state string false none The state abbreviation
street string false none The street name and number
type string false none The type of address
zip string false none The ZIP or postal code

Email

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

An email of the contact

Properties

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

IMS

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

An IMS of the contact

Properties

Name Type Required Restrictions Description
service string false none The type of the the service
userId string false none The 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. Apart from the property formattedName at least one of the other must be set

Properties

Name Type Required Restrictions Description
prefix string false none A prefix of the contact's name
firstName string false none The first name of the contact
middleName string false none The middle name of the contact
lastName string false none The last name of the contact
suffix string false none A suffix of the contact's name
formattedName string true none The completely formatted name

Organisation

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

An organisation associated with the contact

Properties

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

ContactPhone

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

A phone entry of a contact

Properties

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

ContactUrl

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

An URL of a contact

Properties

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

WhatsAppTemplate

{
  "templateId": "string",
  "templateLanguage": "string",
  "components": {
    "header": [
      {
        "type": "text",
        "text": "string",
        "example": {
          "text": "John Doe"
        }
      }
    ],
    "body": [
      {
        "type": "text",
        "text": "string",
        "example": {
          "texts": [
            "John Doe",
            "Order ID 123"
          ]
        }
      }
    ],
    "button": [
      {
        "type": "quick_reply",
        "index": 0,
        "payload": "string"
      }
    ],
    "carousel": {
      "cardIndex": 0,
      "components": {
        "header": [
          {
            "type": "image",
            "image": {
              "url": "string",
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            }
          }
        ],
        "body": [
          {
            "type": "text",
            "text": "string",
            "example": {
              "texts": [
                "John Doe",
                "Order ID 123"
              ]
            }
          }
        ],
        "button": {
          "type": "quick_reply",
          "index": 0,
          "payload": "string"
        }
      }
    }
  }
}

Properties

Name Type Required Restrictions Description
templateId string true none none
templateLanguage string true none none
components WhatsAppTemplateComponents false none none

WhatsAppTemplateComponents

{
  "header": [
    {
      "type": "text",
      "text": "string",
      "example": {
        "text": "John Doe"
      }
    }
  ],
  "body": [
    {
      "type": "text",
      "text": "string",
      "example": {
        "texts": [
          "John Doe",
          "Order ID 123"
        ]
      }
    }
  ],
  "button": [
    {
      "type": "quick_reply",
      "index": 0,
      "payload": "string"
    }
  ],
  "carousel": {
    "cardIndex": 0,
    "components": {
      "header": [
        {
          "type": "image",
          "image": {
            "url": "string",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          }
        }
      ],
      "body": [
        {
          "type": "text",
          "text": "string",
          "example": {
            "texts": [
              "John Doe",
              "Order ID 123"
            ]
          }
        }
      ],
      "button": {
        "type": "quick_reply",
        "index": 0,
        "payload": "string"
      }
    }
  }
}

Properties

Name Type Required Restrictions Description
header [oneOf] false none none

oneOf

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateTextHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateImageHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateVideoHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateDocumentHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateLocationHeaderComponent false none none

continued

Name Type Required Restrictions Description
body [WhatsAppTemplateTextBodyComponent] false none [Body parameter replacement of a template]
button any false none none

oneOf

Name Type Required Restrictions Description
» anonymous WhatsAppQuickReplyButtons false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppCallToActionButtons false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppFlowButtons false none none

continued

Name Type Required Restrictions Description
carousel WhatsAppCarouselComponent false none List of carousel cards. Carousel must have at least one card, and maximum 10.

WhatsAppTemplateTextHeaderComponent

{
  "type": "text",
  "text": "string",
  "example": {
    "text": "John Doe"
  }
}

Properties

Name Type Required Restrictions Description
type string true none none
text string true none none
example WhatsAppTemplateTextHeaderComponentExample true none An example of the header text
Enumerated values
Property Value
type text

WhatsAppTemplateTextHeaderComponentExample

{
  "text": "John Doe"
}

An example of the header text

Properties

Name Type Required Restrictions Description
text string false none Example text

WhatsAppTemplateImageHeaderComponent

{
  "type": "image",
  "image": {
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Properties

Name Type Required Restrictions Description
type string true none none
image WhatsAppTemplateMediaHeader true none Media header specification
Enumerated values
Property Value
type image

WhatsAppTemplateVideoHeaderComponent

{
  "type": "video",
  "video": {
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Properties

Name Type Required Restrictions Description
type string true none none
video WhatsAppTemplateMediaHeader true none Media header specification
Enumerated values
Property Value
type video

WhatsAppTemplateDocumentHeaderComponent

{
  "type": "document",
  "document": {
    "filename": "Test PDF",
    "url": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
}

Properties

Name Type Required Restrictions Description
type string true none none
document WhatsAppTemplateDocumentHeader true none Document media specification
Enumerated values
Property Value
type document

WhatsAppTemplateLocationHeaderComponent

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

Properties

Name Type Required Restrictions Description
type string true none none
location WhatsAppLocation true none Location received or send
Enumerated values
Property Value
type location

WhatsAppTemplateMediaHeader

{
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Media header specification

Properties

None

WhatsAppTemplateDocumentHeader

{
  "filename": "Test PDF",
  "url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Document media specification

Properties

Name Type Required Restrictions Description
filename string false none Additional info for the filename to be displayed.

WhatsAppTemplateTextBodyComponent

{
  "type": "text",
  "text": "string",
  "example": {
    "texts": [
      "John Doe",
      "Order ID 123"
    ]
  }
}

Body parameter replacement of a template

Properties

Name Type Required Restrictions Description
type string true none none
text string true none none
example WhatsAppTemplateTextBodyComponentExample true none Examples of the body parameters.
Enumerated values
Property Value
type text

WhatsAppTemplateTextBodyComponentExample

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

Examples of the body parameters.

Properties

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

WhatsAppCarouselComponent

{
  "cardIndex": 0,
  "components": {
    "header": [
      {
        "type": "image",
        "image": {
          "url": "string",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      }
    ],
    "body": [
      {
        "type": "text",
        "text": "string",
        "example": {
          "texts": [
            "John Doe",
            "Order ID 123"
          ]
        }
      }
    ],
    "button": {
      "type": "quick_reply",
      "index": 0,
      "payload": "string"
    }
  }
}

Carousel card definition

Properties

Name Type Required Restrictions Description
cardIndex integer true none order in which card appears within the card carousel. 0 indicates first card, 1 indicates second...
components WhatsAppCarouselTemplateComponents true none none

WhatsAppCarouselTemplateComponents

{
  "header": [
    {
      "type": "image",
      "image": {
        "url": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      }
    }
  ],
  "body": [
    {
      "type": "text",
      "text": "string",
      "example": {
        "texts": [
          "John Doe",
          "Order ID 123"
        ]
      }
    }
  ],
  "button": {
    "type": "quick_reply",
    "index": 0,
    "payload": "string"
  }
}

Properties

Name Type Required Restrictions Description
header [oneOf] false none none

oneOf

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateImageHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateVideoHeaderComponent false none none

continued

Name Type Required Restrictions Description
body [WhatsAppTemplateTextBodyComponent] false none [Body parameter replacement of a template]
button any false none none

anyOf

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

or

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

WhatsAppQuickReplyButtons

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

Properties

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

WhatsAppCallToActionButtons

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

Properties

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

WhatsAppFlowButtons

[
  {
    "type": "flow",
    "index": 0
  }
]

Properties

Name Type Required Restrictions Description
anonymous [FlowButtonComponent] false none [This type can be used up to one time]

QuickReplyButtonComponent

{
  "type": "quick_reply",
  "index": 0,
  "payload": "string"
}

This type can be used up to three times

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the button. Always quick_reply.
index number true none Determines the index of the button that should be enhanced with the payload.
payload string true none A payload for this quick reply button. Sent back on the MoMessage::PostBack event
Enumerated values
Property Value
type quick_reply

UrlButtonComponent

{
  "type": "url",
  "index": 0,
  "text": "string"
}

This type can be used up to one time

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the button. Always url.
index number true none Determines the index of the button that should be enhanced with a custom parameter
text string true none Which text should be appended to a dynamic URL. Note the requested templates url button must end with {{1}}.
Enumerated values
Property Value
type url

FlowButtonComponent

{
  "type": "flow",
  "index": 0
}

This type can be used up to one time

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the button. Always flow.
index number true none Determines the index of the button that should be enhanced with a custom parameter
Enumerated values
Property Value
type flow

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"
        }
      }
    ]
  }
}

An 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 tomatoes 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"
            }
          ]
        }
      ]
    }
  }
}

An interactive message type

Properties

Name Type Required Restrictions Description
subType string true none none
components WhatsAppInteractiveListComponents true none A list message component. It can have at most 10 rows distributed over at most 10 sections
Enumerated values
Property Value
subType list

WhatsAppInteractiveProductMessage

{
  "subType": "product",
  "components": {
    "header": {
      "type": "text",
      "text": "What about?"
    },
    "body": {
      "type": "text",
      "text": "According to your query, we found this matching product"
    },
    "footer": {
      "type": "text",
      "text": "Your service bot"
    },
    "product": {
      "catalogId": 123987987498123,
      "productId": "My-Product-SKU"
    }
  }
}

Interactive Product Message

Properties

Name Type Required Restrictions Description
subType string true none Determines the type of interactive message. Always product
components WhatsAppInteractiveProductComponents true none An interactive Product Component
Enumerated values
Property Value
subType product

WhatsAppInteractiveProductListMessage

{
  "subType": "productList",
  "components": {
    "header": {
      "type": "text",
      "text": "What about?"
    },
    "body": {
      "type": "text",
      "text": "According to your query, we found this matching products"
    },
    "footer": {
      "type": "text",
      "text": "Your service bot"
    },
    "productList": {
      "catalogId": 12314123123,
      "sections": [
        {
          "title": "Vegan",
          "items": [
            {
              "productId": "sku-1"
            },
            {
              "productId": "sku-2"
            }
          ]
        },
        {
          "title": "Vegetarian",
          "items": [
            {
              "productId": "sku-3"
            },
            {
              "productId": "sku-4"
            }
          ]
        }
      ]
    }
  }
}

Interactive Product List Message

Properties

Name Type Required Restrictions Description
subType string true none Determines the type of interactive message. Always productList
components WhatsAppInteractiveProductListComponents true none A Product List message component. It can have at most 30 products distributed over at most 10 sections
Enumerated values
Property Value
subType productList

WhatsAppInteractiveLocationMessage

{
  "subType": "locationRequest",
  "components": {
    "body": {
      "type": "text",
      "text": "Hi, please share your location with us by clicking the button below"
    }
  }
}

Interactive Location Message

Properties

Name Type Required Restrictions Description
subType string true none Determines the type of interactive message. Always locationRequest
components WhatsAppInteractiveLocationComponents true none A Location message component. It contains only body text. Send location button that users can tap is automatically added.
Enumerated values
Property Value
subType locationRequest

WhatsAppInteractiveFlowMessage

{
  "subType": "flow",
  "components": {
    "header": {
      "type": "text",
      "text": "Flow header component"
    },
    "body": {
      "type": "text",
      "text": "Flow body component"
    },
    "footer": {
      "type": "text",
      "text": "Flow footer component"
    },
    "flow": {
      "flowToken": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
      "flowId": 1234567890123456,
      "flowCta": "Click to see the flow",
      "flowAction": "navigate",
      "flowActionPayload": {
        "screen": "DETAILS",
        "data": {
          "product_name": "name",
          "product_description": "description",
          "product_price": 100
        }
      }
    }
  }
}

Interactive Flow Message

Properties

Name Type Required Restrictions Description
subType string true none Determines the type of interactive message. Always flow
components WhatsAppInteractiveFlowComponents true none A Flow message components. It contains optional header and footer text component and mandatory body text and main flow component.
Enumerated values
Property Value
subType flow

WhatsAppInteractiveAddressMessage

{
  "subType": "address",
  "components": {
    "header": {
      "type": "text",
      "text": "Address header component"
    },
    "body": {
      "type": "text",
      "text": "Address body component"
    },
    "footer": {
      "type": "text",
      "text": "Address footer component"
    },
    "address": {
      "country": "IN",
      "values": {
        "name": "Test name",
        "phoneNumber": 91012345678,
        "inPinCode": 123456,
        "houseNumber": 21,
        "floorNumber": 3,
        "address": "Some address in India",
        "city": "Mumbai"
      },
      "savedAddresses": {
        "id": 1234,
        "value": {
          "name": "Customer name",
          "phoneNumber": 91012345678,
          "inPinCode": 123456,
          "address": "Some address in India",
          "city": "Mumbai"
        }
      },
      "validationErrors": {
        "inPinCode": "We could not locate this pin code."
      }
    }
  }
}

Interactive Address Message. Only available in India and Singapore

Properties

Name Type Required Restrictions Description
subType string true none Determines the type of interactive message. Always address
components WhatsAppInteractiveAddressComponents true none A interactive address message components. It contains optional header and footer text component and mandatory body text and main address component.
Enumerated values
Property Value
subType address

WhatsAppInteractiveButtonComponents

{
  "header": {
    "type": "text",
    "text": "string",
    "example": {
      "text": "John Doe"
    }
  },
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "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 WhatsAppTemplateTextHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateImageHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateVideoHeaderComponent false none none

xor

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateDocumentHeaderComponent false none none

continued

Name Type Required Restrictions Description
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
buttons [WhatsAppInteractiveButton] true none [An interactive message button]

WhatsAppInteractiveButton

{
  "type": "reply",
  "reply": {
    "payload": "string",
    "title": "string"
  }
}

An interactive message button

Properties

Name Type Required Restrictions Description
type string true none The type of button. Always "reply"
reply object true none The reply button specification
» payload string true none The ID of the reply button. Must be unique within the same messaging request
» title string true none The caption or title of the button
Enumerated values
Property Value
type reply

WhatsAppInteractiveListComponents

{
  "header": {
    "type": "text",
    "text": "string",
    "example": {
      "text": "John Doe"
    }
  },
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "text",
    "text": "string"
  },
  "list": {
    "title": "Choose from this list",
    "sections": [
      {
        "title": "string",
        "rows": [
          {
            "payload": "string",
            "title": "string",
            "description": "string"
          }
        ]
      }
    ]
  }
}

A list message component. It can have at most 10 rows distributed over at most 10 sections

Properties

Name Type Required Restrictions Description
header WhatsAppTemplateTextHeaderComponent false none none
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
list WhatsAppInteractiveListContent true none A definition of a WhatsApp interactive list

WhatsAppInteractiveListContent

{
  "title": "Choose from this list",
  "sections": [
    {
      "title": "string",
      "rows": [
        {
          "payload": "string",
          "title": "string",
          "description": "string"
        }
      ]
    }
  ]
}

A 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"
    }
  ]
}

A section of a list message.

Properties

Name Type Required Restrictions Description
title string false none The 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"
}

A row item of a list message

Properties

Name Type Required Restrictions Description
payload string true none The ID of the item, must be unique within the request
title string true none The caption of the item in the list
description string false none An optional description of the item

WhatsAppInteractiveProductComponents

{
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "text",
    "text": "string"
  },
  "product": {
    "catalogId": "12432134",
    "productId": "Test SKU"
  }
}

An interactive Product Component

Properties

Name Type Required Restrictions Description
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
product object true none A product specification to be sent to the customer
» catalogId string true none The Catalog ID of the Facebook catalog, must be linked to the WhatsApp business account
» productId string true none The Own Product ID or SKU for the product. Must be configured on the Facebook catalog

WhatsAppInteractiveProductListComponents

{
  "header": {
    "type": "text",
    "text": "string",
    "example": {
      "text": "John Doe"
    }
  },
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "text",
    "text": "string"
  },
  "productList": {
    "catalogId": 2134432423,
    "sections": [
      {
        "title": "string",
        "items": [
          {
            "productId": "Test SKU"
          }
        ]
      }
    ]
  }
}

A Product List message component. It can have at most 30 products distributed over at most 10 sections

Properties

Name Type Required Restrictions Description
header WhatsAppTemplateTextHeaderComponent true none none
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
productList WhatsAppInteractiveProductListContent true none The definition of a WhatsApp product list

WhatsAppInteractiveProductListContent

{
  "catalogId": 2134432423,
  "sections": [
    {
      "title": "string",
      "items": [
        {
          "productId": "Test SKU"
        }
      ]
    }
  ]
}

The definition of a WhatsApp product list

Properties

Name Type Required Restrictions Description
catalogId string false none The Catalog ID of the Facebook catalog, must be linked to the WhatsApp business account
sections [WhatsAppProductListSection] true none Sections of the list message

WhatsAppProductListSection

{
  "title": "string",
  "items": [
    {
      "productId": "Test SKU"
    }
  ]
}

A section of a product list message.

Properties

Name Type Required Restrictions Description
title string false none The title of the section mandatory in case of multiple sections
items [WhatsAppProductListItem] true none Products of this section

WhatsAppProductListItem

{
  "productId": "Test SKU"
}

A single item on the product list

Properties

Name Type Required Restrictions Description
productId string true none The Own Product ID or SKU for the product. Must be configured on the Facebook catalog

WhatsAppInteractiveLocationComponents

{
  "body": {
    "type": "text",
    "text": "string"
  }
}

A Location message component. It contains only body text. Send location button that users can tap is automatically added.

Properties

Name Type Required Restrictions Description
body WhatsAppInteractiveTextContent true none The message body of an interactive message

WhatsAppInteractiveFlowComponents

{
  "header": {
    "type": "text",
    "text": "string",
    "example": {
      "text": "John Doe"
    }
  },
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "text",
    "text": "string"
  },
  "flow": {
    "mode": "published",
    "flowToken": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
    "flowId": 1234567890123456,
    "flowCta": "Click for the flow",
    "flowAction": "navigate",
    "flowActionPayload": {
      "screen": "SIGN_UP",
      "data": {
        "product_name": "name",
        "product_price": 100
      }
    }
  }
}

A Flow message components. It contains optional header and footer text component and mandatory body text and main flow component.

Properties

Name Type Required Restrictions Description
header WhatsAppTemplateTextHeaderComponent false none none
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
flow WhatsAppInteractiveFlowContent true none The definition of a WhatsApp Flow content

WhatsAppInteractiveFlowContent

{
  "mode": "published",
  "flowToken": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
  "flowId": 1234567890123456,
  "flowCta": "Click for the flow",
  "flowAction": "navigate",
  "flowActionPayload": {
    "screen": "SIGN_UP",
    "data": {
      "product_name": "name",
      "product_price": 100
    }
  }
}

The definition of a WhatsApp Flow content

Properties

Name Type Required Restrictions Description
mode string false none The state of the flow being sent. The Flow can be in either published or draft mode. Default value is published.
flowToken string true none Flow token that is generated by the user to serve as an identifier.
flowId string true none Unique ID of the Flow. ID is provided by Meta, and can be found on Meta's Business Manager.
flowCta string true none Text on "Call to action" button that is going to start the flow.
flowAction string true none Possible values are navigate and data_exchange. Default value is navigate. Use navigate to predefine the first screen as part of the message. Use data_exchange for advanced use-cases where the first screen is provided by your endpoint.
flowActionPayload object false none Required only if flow_action is navigate.
» screen string true none The ID of the first Screen.
» data object false none Optional input data for the first Screen of the Flow.

WhatsAppInteractiveAddressComponents

{
  "header": {
    "type": "text",
    "text": "string",
    "example": {
      "text": "John Doe"
    }
  },
  "body": {
    "type": "text",
    "text": "string"
  },
  "footer": {
    "type": "text",
    "text": "string"
  },
  "address": {
    "country": "IN",
    "values": {
      "name": "string",
      "phoneNumber": "string",
      "houseNumber": "string",
      "floorNumber": "string",
      "towerNumber": "string",
      "buildingName": "string",
      "address": "string",
      "landmarkArea": "string",
      "unitNumber": "string",
      "city": "string",
      "state": "string",
      "inPinCode": "string",
      "sgPostCode": "string"
    },
    "savedAddresses": {
      "id": 12345,
      "value": {
        "name": "string",
        "phoneNumber": "string",
        "houseNumber": "string",
        "floorNumber": "string",
        "towerNumber": "string",
        "buildingName": "string",
        "address": "string",
        "landmarkArea": "string",
        "unitNumber": "string",
        "city": "string",
        "state": "string",
        "inPinCode": "string",
        "sgPostCode": "string"
      }
    },
    "validationErrors": {
      "name": "string",
      "phoneNumber": "string",
      "houseNumber": "string",
      "floorNumber": "string",
      "towerNumber": "string",
      "buildingName": "string",
      "address": "string",
      "landmarkArea": "string",
      "unitNumber": "string",
      "city": "string",
      "state": "string",
      "inPinCode": "string",
      "sgPostCode": "string"
    }
  }
}

A interactive address message components. It contains optional header and footer text component and mandatory body text and main address component.

Properties

Name Type Required Restrictions Description
header WhatsAppTemplateTextHeaderComponent false none none
body WhatsAppInteractiveTextContent true none The message body of an interactive message
footer WhatsAppInteractiveFooterContent false none The footer of an interactive message
address WhatsAppInteractiveAddressContent true none The definition of a WhatsApp Address content

WhatsAppInteractiveAddressContent

{
  "country": "IN",
  "values": {
    "name": "string",
    "phoneNumber": "string",
    "houseNumber": "string",
    "floorNumber": "string",
    "towerNumber": "string",
    "buildingName": "string",
    "address": "string",
    "landmarkArea": "string",
    "unitNumber": "string",
    "city": "string",
    "state": "string",
    "inPinCode": "string",
    "sgPostCode": "string"
  },
  "savedAddresses": {
    "id": 12345,
    "value": {
      "name": "string",
      "phoneNumber": "string",
      "houseNumber": "string",
      "floorNumber": "string",
      "towerNumber": "string",
      "buildingName": "string",
      "address": "string",
      "landmarkArea": "string",
      "unitNumber": "string",
      "city": "string",
      "state": "string",
      "inPinCode": "string",
      "sgPostCode": "string"
    }
  },
  "validationErrors": {
    "name": "string",
    "phoneNumber": "string",
    "houseNumber": "string",
    "floorNumber": "string",
    "towerNumber": "string",
    "buildingName": "string",
    "address": "string",
    "landmarkArea": "string",
    "unitNumber": "string",
    "city": "string",
    "state": "string",
    "inPinCode": "string",
    "sgPostCode": "string"
  }
}

The definition of a WhatsApp Address content

Properties

Name Type Required Restrictions Description
country string true none Only available in India (IN) and Singapore (SG)
values WhatsAppInteractiveBasicAddressValue false none none
savedAddresses object false none Saved addresses previously associated with the user.
» id string true none Id of saved address
» value WhatsAppInteractiveBasicAddressValue true none none
validationErrors WhatsAppInteractiveAddressValidationErrors false none Validations errors that will be thrown in order to validate address fields.

WhatsAppInteractiveBasicAddressValue

{
  "name": "string",
  "phoneNumber": "string",
  "houseNumber": "string",
  "floorNumber": "string",
  "towerNumber": "string",
  "buildingName": "string",
  "address": "string",
  "landmarkArea": "string",
  "unitNumber": "string",
  "city": "string",
  "state": "string",
  "inPinCode": "string",
  "sgPostCode": "string"
}

Properties

allOf

Name Type Required Restrictions Description
anonymous WhatsAppInteractiveBasicAddressValuePayload false none A fields that represent address value. Some fields are available just for specific country.

and

Name Type Required Restrictions Description
anonymous object false none none
» inPinCode string false none String representation of pin code. Max size is 6 digits. Supported countries India
» sgPostCode string false none String representation of pin code. Max size is 6 digits. Supported countries Singapore

WhatsAppInteractiveAddressValidationErrors

{
  "name": "string",
  "phoneNumber": "string",
  "houseNumber": "string",
  "floorNumber": "string",
  "towerNumber": "string",
  "buildingName": "string",
  "address": "string",
  "landmarkArea": "string",
  "unitNumber": "string",
  "city": "string",
  "state": "string",
  "inPinCode": "string",
  "sgPostCode": "string"
}

Validations errors that will be thrown in order to validate address fields.

Properties

allOf

Name Type Required Restrictions Description
anonymous WhatsAppInteractiveBasicAddressValuePayload false none A fields that represent address value. Some fields are available just for specific country.

and

Name Type Required Restrictions Description
anonymous object false none none
» inPinCode string false none Error message for validating pin code
» sgPostCode string false none Error message for validating pin code

WhatsAppInteractiveBasicAddressValuePayload

{
  "name": "string",
  "phoneNumber": "string",
  "houseNumber": "string",
  "floorNumber": "string",
  "towerNumber": "string",
  "buildingName": "string",
  "address": "string",
  "landmarkArea": "string",
  "unitNumber": "string",
  "city": "string",
  "state": "string"
}

A fields that represent address value. Some fields are available just for specific country.

Properties

Name Type Required Restrictions Description
name string false none Supported countries India, Singapore
phoneNumber string false none Supported countries India, Singapore
houseNumber string false none Supported countries India, Singapore
floorNumber string false none Supported countries India, Singapore
towerNumber string false none Supported countries India, Singapore
buildingName string false none Supported countries India, Singapore
address string false none Supported countries India, Singapore
landmarkArea string false none Supported countries India
unitNumber string false none Supported countries Singapore
city string false none Supported countries India, Singapore
state string false none Supported countries India

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 The address of the business
description string false none A brief introduction of the business
email string false none The contact mail address
websites [string] false none Websites of the business
vertical string false none The 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"
}

A 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
{
  "link": "https://pps.whatsapp.net/v/123123"
}

A link to the profile logo

Properties

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

WhatsAppCommerceSettings

{
  "enabled": true
}

Properties

Name Type Required Restrictions Description
enabled boolean false none none

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"
    }
  }
]

A list of WhatsApp Business Accounts. Might be empty

Properties

Name Type Required Restrictions Description
anonymous [WhatsAppAccount] false none A 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 The ID of the WhatsApp Business Account
whatsAppAccountName string false none The name of the WhatsApp Business Account
businessName string false none The name of the business owning the Facebook Business Manager
templateNamespace string false none A template namespace assigned to the WhatsApp Business Account.

This is used internally and here stated for completeness.
facebookBusinessManagerId number 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 The account that can manage (edit, ...) the entity

WhatsAppPhoneNumbers

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

A list of phone numbers on WhatsApp. Might be empty

Properties

Name Type Required Restrictions Description
anonymous [WhatsAppPhoneNumber] false none A list of phone numbers on WhatsApp. Might be empty

WhatsAppPhoneNumber

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

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 next 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 The status of the number
whatsAppAccountId string(uuid) false none The ID of the WhatsApp Business Account the number belongs to.
managedBy CPaaSAccount false none The account that can manage (edit, ...) the entity
messagingVia CPaaSAccount false none The 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
nameStatus string false none Status of Display Name approval by Meta
isOfficialBusinessAccount boolean false none True if this phone number is recognized as official business account by Meta (green checkmark badge)
Enumerated values
Property Value
qualityRating GREEN
qualityRating RED
qualityRating YELLOW
status CONNECTED
status PENDING
status FLAGGED
status RESTRICTED
status OFFLINE
status DISCONNECTED
messagingTier TIER_NOT_SET
messagingTier TIER_50
messagingTier TIER_250
messagingTier TIER_1K
messagingTier TIER_10K
messagingTier TIER_100K
messagingTier UNLIMITED

CPaaSAccount

{
  "accountName": "someaccount"
}

The CPaaS account behind the API key

Properties

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

WhatsAppTemplateRequest

{
  "name": "string",
  "category": "MARKETING",
  "localizations": [
    {
      "language": "en",
      "components": [
        {
          "type": "BODY",
          "text": "string"
        }
      ],
      "messageSendTimeToLiveSeconds": 60
    }
  ],
  "allowCategoryChange": false
}

A request for an additional WhatsApp template

Properties

Name Type Required Restrictions Description
name string true none The name of the template
category TemplateCategory true none The category of the template
localizations [LocalizationRequest] true none Localizations of the template
allowCategoryChange boolean false none If true, let Meta allow to change category

LocalizationRequest

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

A request for a new localization of a template

Properties

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

oneOf

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

xor

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

xor

Name Type Required Restrictions Description
» anonymous CarouselTemplateRequest false none A carousel template definition. Must contain text body and carousel component

continued

Name Type Required Restrictions Description
messageSendTimeToLiveSeconds integer false none If WhatsApp is unable to deliver a message to a user, we will continue attempting to deliver the message for a period of time known as a time-to-live. Newly created authentication templates have a default time-to-live of 10 minutes. To override the default time-to-live when creating an authentication template set this field to value between 60 and 600 seconds. Additionally, set -1 to set time-to-live to message default value. This will set time-to-live to 24 hours (or 30 days for On-Premises API).

TemplatePatchRequest

{
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "string"
    }
  ]
}

A request to edit an existing template

Properties

Name Type Required Restrictions Description
category TemplateCategory false none The category of the template
components any false none Components defining the desired change in templates definition

oneOf

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

xor

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

xor

Name Type Required Restrictions Description
» anonymous CarouselTemplateRequest false none A carousel template definition. Must contain text body and carousel component

NotificationTemplateRequest

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

A request for a standard template (notification) without rich media components

Properties

Name Type Required Restrictions Description
type string true none The 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"
    }
  }
]

A rich media template definition. Must contain at least the body component

Properties

anyOf

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

or

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

or

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

or

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

CarouselTemplateRequest

[
  {
    "type": "BODY",
    "text": "Some bubble text"
  },
  {
    "type": "CAROUSEL",
    "cards": [
      {
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "example": {
              "url": "image example url card1"
            }
          },
          {
            "type": "BODY",
            "text": "Some body card1 text"
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "QUICK_REPLY",
                "text": "Send more like this card1"
              },
              {
                "type": "URL",
                "text": "Buy now card1",
                "url": "some url"
              }
            ]
          }
        ]
      },
      {
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "example": {
              "url": "image example url card2"
            }
          },
          {
            "type": "BODY",
            "text": "Some body card2 text"
          },
          {
            "type": "BUTTONS",
            "buttons": [
              {
                "type": "QUICK_REPLY",
                "text": "Send more like this card2"
              },
              {
                "type": "URL",
                "text": "Buy now card2",
                "url": "some url"
              }
            ]
          }
        ]
      }
    ]
  }
]

A carousel template definition. Must contain text body and carousel component

Properties

anyOf

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

or

Name Type Required Restrictions Description
anonymous WhatsAppTemplateCarouselComponentRequest false none A carousel component of a template

WhatsAppTemplateHeaderComponentRequest

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

A header component of a template

Properties

oneOf

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

xor

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

xor

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

WhatsAppTemplateTextHeaderComponentRequest

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

A 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 What kind of header
text string true none The text that should be displayed as the header. Can contain 1 variable
example WhatsAppTemplateTextHeaderComponentRequestExample true none An example of the header text
Enumerated values
Property Value
type HEADER
format TEXT

WhatsAppTemplateTextHeaderComponentRequestExample

{
  "text": "John Doe"
}

An example of the header text

Properties

Name Type Required Restrictions Description
text string false none An example text

WhatsAppTemplateLocationHeaderComponentRequest

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

A 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 What kind of header
Enumerated values
Property Value
type HEADER
format LOCATION

WhatsAppTemplateMediaHeaderComponentRequest

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

A 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 What kind of header
example WhatsAppTemplateMediaHeaderComponentRequestExample true none An example of a media
Enumerated values
Property Value
type HEADER
format IMAGE
format DOCUMENT
format VIDEO

WhatsAppTemplateMediaHeaderComponentRequestExample

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

An example of a media

Properties

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

WhatsAppTemplateBodyComponentRequest

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

A 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 false none The specification of the body text (1--1024 chars). Mandatory for all non-authentication templates
addSecurityRecommendation boolean false none Only used for AUTHENTICATION templates. Adds security recommendation to the default OTP text.
example WhatsAppTemplateBodyComponentRequestExample false none Examples of 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 body parameters. All parameters of the body must have an example

Properties

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

WhatsAppTemplateFooterComponentRequest

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

A footer component of a template

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the component
text string false none The specification of the footer text (1--60 chars). Mandatory for all non-authentication templates
codeExpirationMinutes integer false none Only used in AUTHENTICATION templates. Adds an expiration note to the default OTP text.
Enumerated values
Property Value
type FOOTER

WhatsAppTemplateButtonComponentRequest

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

A 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 WhatsAppQuickReplyButtonsRequest false none Quick Reply buttons

xor

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

xor

Name Type Required Restrictions Description
» anonymous WhatsAppOtpButtonsRequest false none OTP buttons

xor

Name Type Required Restrictions Description
» anonymous WhatsAppFlowButtonsRequest false none Flows buttons
Enumerated values
Property Value
type BUTTONS

WhatsAppQuickReplyButtonsRequest

[
  {
    "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!"
}

A quick reply button, when clicked the caption and the dynamic payload are returned.

Properties

Name Type Required Restrictions Description
type string true none The type of this button
text string true none The caption of the button
Enumerated values
Property Value
type QUICK_REPLY

WhatsAppOtpButtonsRequest

[
  {
    "type": "OTP",
    "otpType": "COPY_CODE",
    "text": "Copy code."
  }
]

OTP buttons

Properties

anyOf

Name Type Required Restrictions Description
anonymous WhatsAppCopyCodeOtpButton false none A copy code button. When clicked, the code is copied to handsets clipboard.

or

Name Type Required Restrictions Description
anonymous WhatsAppOneTapOtpButton false none A one-tap otp button. Only works for android at the moment, see https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake

or

Name Type Required Restrictions Description
anonymous WhatsAppZeroTapOtpButton false none A zero-tap otp button. Only works for android at the moment, see https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake

WhatsAppCopyCodeOtpButton

{
  "type": "OTP",
  "otpType": "COPY_CODE",
  "text": "Copy code."
}

A copy code button. When clicked, the code is copied to handsets clipboard.

Properties

Name Type Required Restrictions Description
type string true none The type of this button, 'OTP'
otpType string true none The subtype of this button, 'COPY_CODE'
text string true none The caption of the copy code button.
Enumerated values
Property Value
type OTP
otpType COPY_CODE

WhatsAppOneTapOtpButton

{
  "type": "OTP",
  "otpType": "ONE_TAP",
  "text": "Copy code.",
  "autofillText": "Autofill",
  "packageName": "string",
  "signatureHash": "string"
}

A one-tap otp button. Only works for android at the moment, see https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake

Properties

Name Type Required Restrictions Description
type string true none The type of this button, 'OTP'
otpType string true none The subtype of this button, 'ONE_TAP'
text string true none The caption of the fallback copy code button, if one-tap is not available.
autofillText string true none The caption of the autofill button.
packageName string true none Your android app's package name.
signatureHash string true none Your app signing key hash.
Enumerated values
Property Value
type OTP
otpType ONE_TAP

WhatsAppZeroTapOtpButton

{
  "type": "OTP",
  "otpType": "ZERO_TAP",
  "text": "Copy code.",
  "autofillText": "Autofill",
  "packageName": "string",
  "signatureHash": "string",
  "zeroTapTermsAccepted": true
}

A zero-tap otp button. Only works for android at the moment, see https://developers.facebook.com/docs/whatsapp/business-management-api/authentication-templates#handshake

Properties

Name Type Required Restrictions Description
type string true none The type of this button, 'OTP'
otpType string true none The subtype of this button, 'ZERO_TAP'
text string false none The caption of the fallback copy code button, if zero-tap is not available.
autofillText string false none The caption of the autofill button.
packageName string true none Your android app's package name.
signatureHash string true none Your app signing key hash.
zeroTapTermsAccepted boolean true none Set to true to indicate that you understand and accept zero-tap authentication policy. If set to false, the template will not be created as you need to accept zero-tap terms before creating zero-tap enabled message templates.
Enumerated values
Property Value
type OTP
otpType ZERO_TAP

WhatsAppCallToActionButtonsRequest

[
  {
    "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 A call to action button that opens the specified URL when clicked

or

Name Type Required Restrictions Description
anonymous WhatsAppPhoneNumberButton false none A 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"
  }
}

A call to action button that opens the specified URL when clicked

Properties

Name Type Required Restrictions Description
type string true none The type of this button
text string true none The 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 true none An example of a dynamic URL button.
Enumerated values
Property Value
type URL

WhatsAppURLButtonExample

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

An example of a dynamic URL button.

Properties

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

WhatsAppPhoneNumberButton

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

A call to action button that initiates a call when clicked

Properties

Name Type Required Restrictions Description
type string true none The type of this button
text string true none The caption for this button
phoneNumber string false none The phone number that will be called when clicking on the button.
Enumerated values
Property Value
type PHONE_NUMBER

WhatsAppFlowButtonsRequest

[
  {
    "type": "FLOW",
    "text": "Click for the flow",
    "flowId": 1234567890123456,
    "flowAction": "navigate",
    "navigateScreen": "details"
  }
]

Flows buttons

Properties

None

WhatsAppFlowButton

{
  "type": "FLOW",
  "text": "Click for the flow",
  "flowId": 1234567890123456,
  "flowAction": "navigate",
  "navigateScreen": "details"
}

A flow button that opens the specified flow defined under flowId in Meta's business manager

Properties

Name Type Required Restrictions Description
type string true none The type of this button. Always FLOW
text string true none The caption of the button
flowId string true none The unique ID of a Flow from Meta's Business manager
flowAction string true none Possible values are navigate and data_exchange. Default value is navigate. Use navigate to predefine the first screen as part of the message. Use data_exchange for advanced use-cases where the first screen is provided by your endpoint.
navigateScreen string false none Required if flowAction is navigate. The unique ID of the Screen in the Flow.
Enumerated values
Property Value
type FLOW

WhatsAppTemplateCarouselComponentRequest

{
  "type": "CAROUSEL",
  "cards": [
    {
      "components": [
        {
          "type": "HEADER",
          "format": "IMAGE",
          "example": {
            "url": "https://www.my.com/image.jpg"
          }
        },
        {
          "type": "HEADER",
          "format": "IMAGE",
          "example": {
            "url": "https://www.my.com/image.jpg"
          }
        },
        {
          "type": "HEADER",
          "format": "IMAGE",
          "example": {
            "url": "https://www.my.com/image.jpg"
          }
        }
      ]
    }
  ]
}

A carousel component of a template

Properties

Name Type Required Restrictions Description
type string true none Determines the type of the component
cards WhatsAppTemplateCards true none Carousel cards definition. Must contain at least one card component, maximum 10.
Enumerated values
Property Value
type CAROUSEL

WhatsAppTemplateCards

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

Carousel cards definition. Must contain at least one card component, maximum 10.

Properties

None

WhatsAppTemplateCardComponent

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

A template card object. Must have media header (image or video), text body, and buttons components. Footer component is not allowed. Minimum one button, maximum two are allowed. Buttons can be the same or a mix of type quickly_reply, url or phone_numbers are allowed. Media header format and button types must be the same across all cards that make up a carousel template.

Properties

Name Type Required Restrictions Description
components CarouselCardComponents true none Components defining the carousel card.

CarouselCardComponents

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

A carousel card components definition. Must have media header (image or video), text body, and buttons components. Footer component is not allowed.

Properties

anyOf

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

or

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

or

Name Type Required Restrictions Description
anonymous WhatsAppCarouselTemplateButtonComponentRequest false none A button component of a carousel template. Allowed buttons are quick_reply, url or phone_numbers. Must have at least one button, maximum two.

WhatsAppCarouselTemplateButtonComponentRequest

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

A button component of a carousel template. Allowed buttons are quick_reply, url or phone_numbers. Must have at least one button, maximum two.

Properties

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

anyOf

Name Type Required Restrictions Description
» anonymous WhatsAppQuickReplyButton false none A quick reply button, when clicked the caption and the dynamic payload are returned.

or

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

or

Name Type Required Restrictions Description
» anonymous WhatsAppPhoneNumberButton false none A call to action button that initiates a call when clicked
Enumerated values
Property Value
type BUTTONS

WhatsAppTemplates

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

A list of WhatsApp templates

Properties

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

WhatsAppTemplateResponse

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

A WhatsApp template

Properties

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

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."
    ]
  },
  "messageSendTimeToLiveSeconds": 120
}

A localization of a template

Properties

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

anyOf

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

or

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

or

Name Type Required Restrictions Description
» anonymous WhatsAppTemplateFooterComponentResponse false none A 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 the localization expires.
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
messageSendTimeToLiveSeconds integer false none If WhatsApp is unable to deliver a message to a user, we will continue attempting to deliver the message for a period of time known as a time-to-live. Newly created authentication templates have a default time-to-live of 10 minutes. Possible values for an authentication template is value between 60 and 600 seconds. Additionally, -1 is set time-to-live for message default value (24 hours Cloud API or 30 days for On-Premises API).
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}}!"
}

A header component of a template

Properties

Name Type Required Restrictions Description
type string true none A component type
format string true none What kind of header
text string false none The textual part in the case the format is TEXT
Enumerated values
Property Value
type HEADER
format IMAGE
format TEXT
format DOCUMENT
format VIDEO

WhatsAppTemplateBodyComponentResponse

{
  "type": "BODY",
  "text": "Hi {{1}}! Enjoy the spec!"
}

A body component of a template

Properties

Name Type Required Restrictions Description
type string true none A component type
text string true none The specification of the body text
Enumerated values
Property Value
type BODY

WhatsAppTemplateFooterComponentResponse

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

A footer component of a template

Properties

Name Type Required Restrictions Description
type string true none A component type
text string false none The specification of the footer text
Enumerated values
Property Value
type FOOTER

TemplateCategory

"MARKETING"

The category of the template

Properties

Name Type Required Restrictions Description
anonymous string false none The category of the template
Enumerated values
Property Value
anonymous MARKETING
anonymous UTILITY
anonymous AUTHENTICATION

LanguageCode

"en"

The supported language codes, according to Supported Languages

Properties

Name Type Required Restrictions Description
anonymous string false none The 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 ka
anonymous kk
anonymous kn
anonymous ko
anonymous ky_KG
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 rw_RW
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

WhatsAppChannelResponse

{
  "channel": "whatsapp",
  "scopes": [
    "messages:read",
    "profile:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

WhatsAppChannelResponses

[
  {
    "channel": "whatsapp",
    "scopes": [
      "messages:read",
      "profile:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

ChannelCallback

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [string] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11

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 A textual description of why the quality score is set to the value.
Only present when the score is YELLOW or RED
Enumerated values
Property Value
score unknown
score GREEN
score YELLOW
score RED

WhatsAppFlows

[
  {
    "id": 12345678901234,
    "name": "Flow test",
    "status": "DRAFT",
    "categories": [
      "OTHER"
    ],
    "validationErrors": []
  }
]

A list of WhatsApp flows

Properties

Name Type Required Restrictions Description
anonymous [WhatsAppBasicFlow] false none A list of WhatsApp flows

WhatsAppBasicFlow

{
  "id": 12345678901234,
  "name": "Flow test",
  "status": "DRAFT",
  "categories": [
    "OTHER"
  ],
  "validationErrors": []
}

A WhatsApp basic flow info

Properties

Name Type Required Restrictions Description
id string false none The ID of the WhatsApp Flow.
name string false none The name of the flow
status string false none Status of the flow
categories [anyOf] false none A list of Flow categories. Flow must have at least one category
validationErrors [FlowValidationError] false none The list of flow validation errors. List is empty if the flow has no errors.
Enumerated values
Property Value
status DRAFT
status DEPRECATED
status PUBLISHED

WhatsAppFlowDetail

{
  "id": 1234567890123456,
  "name": "Test flow",
  "status": "DRAFT",
  "categories": [
    "SIGN_UP",
    "OTHER"
  ],
  "validationErrors": {
    "error": "INVALID_PROPERTY",
    "errorType": "JSON_SCHEMA_ERROR",
    "message": "The property 'initial-text' cannot be specified",
    "lineStart": 46,
    "lineEnd": 46,
    "columnStart": 17,
    "columnEnd": 30
  },
  "jsonVersion": 3,
  "dataApiVersion": 3,
  "endpointUri": "Test flow",
  "preview": {
    "previewUrl": "https://previewLink.com/flows/1234567890123/preview/?token=bf747eb7",
    "expiresAt": "2024-02-21T15:15:32+0000"
  }
}

A WhatsApp flow detail info

Properties

Name Type Required Restrictions Description
id string false none The ID of the WhatsApp Flow.
name string false none The name of the flow
status string false none Status of the flow
categories [anyOf] false none A list of Flow categories. Flow must have at least one category
validationErrors [FlowValidationError] false none The list of flow validation errors. List is empty if the flow has no errors.
jsonVersion string false none The version specified by the developer in the Flow JSON asset uploaded.
dataApiVersion string false none The version of the Data API specified by the developer in the Flow JSON asset uploaded. Only for Flows with an Endpoint.
endpointUri string false none The URL of the WA Flow Endpoint specified by the developer via API or in the Builder UI.
preview WhatsAppFlowPreview false none A WhatsApp flow preview link to visualize the flow and its expiry time.
Enumerated values
Property Value
status DRAFT
status DEPRECATED
status PUBLISHED

FlowValidationError

{
  "error": "INVALID_PROPERTY",
  "errorType": "JSON_SCHEMA_ERROR",
  "message": "The property 'initial-text' cannot be specified",
  "lineStart": 46,
  "lineEnd": 46,
  "columnStart": 17,
  "columnEnd": 30
}

A validation error of a flow

Properties

Name Type Required Restrictions Description
error string false none Error name of the flow
errorType string false none Type of the error
message string false none Error message
lineStart string false none The line where error starts, in json flow
lineEnd string false none The line where error ends, in json flow
columnStart string false none The column where error starts, in json flow
columnEnd string false none The column where error ends, in json flow

FlowCategory

"SIGN_UP"

Flow's category

Properties

Name Type Required Restrictions Description
anonymous string false none Flow's category
Enumerated values
Property Value
anonymous SIGN_UP
anonymous SIGN_IN
anonymous APPOINTMENT_BOOKING
anonymous LEAD_GENERATION
anonymous CONTACT_US
anonymous CUSTOMER_SUPPORT
anonymous SURVEY
anonymous OTHER

WhatsAppFlowPreview

{
  "previewUrl": "https://previewLink.com/flows/1234567890123/preview/?token=bf747eb7",
  "expiresAt": "2024-02-21T15:15:32+0000"
}

A WhatsApp flow preview link to visualize the flow and its expiry time.

Properties

Name Type Required Restrictions Description
previewUrl string false none Link for the preview page. This link is public, but it will expire in 30 days, or if you call the API with invalidate=true which will generate a new link.
expiresAt string false none Time when the link will expire and the developer needs to call the API again to get a new link (30 days from link creation).

CreateFlow

{
  "flowId": 1234567890123456
}

Create flow response

Properties

Name Type Required Restrictions Description
flowId string false none The ID of the WhatsApp Flow.

WhatsAppFlowAssets

[
  {
    "name": "flow.json",
    "assetType": "FLOW_JSON",
    "downloadUrl": "https://scontent.xx.fbcdn.net/m1/v/test"
  }
]

A list of Flow assets

Properties

Name Type Required Restrictions Description
anonymous [WhatsFlowAsset] false none A list of Flow assets

WhatsFlowAsset

{
  "name": "flow.json",
  "assetType": "FLOW_JSON",
  "downloadUrl": "https://scontent.xx.fbcdn.net/m1/v/test"
}

A WhatsApp basic flow info

Properties

Name Type Required Restrictions Description
name string false none Asset name
assetType string false none Asset type. Always FLOW_JSON
downloadUrl string false none The url to download json asset

Viber

Version: v3.2

Specification Release Notes Other versions

The Conversations API 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 Video Video & Text Video & Text & Button 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

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/conversations/v3/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

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

const inputBody = '{
  "to": "+123234234",
  "from": "545345345",
  "channel": "viber",
  "messagePurpose": "promotion",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/messages", data)
    req.Header = headers

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

POST /messages

Send messages via this path.

Body parameter

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "viber",
  "messagePurpose": "promotion",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}

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",
  "timestamp": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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 response after the server has accepted the request 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 The default response in case of any other error. Please check the error object for details Problem

Send a bulk message

Code samples

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

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

const inputBody = '{
  "to": "+1233423454",
  "from": "+1233423454",
  "messagePurpose": "promotion",
  "rateType": "promotion",
  "channel": "viber",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/bulks", data)
    req.Header = headers

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

POST /bulks

Send bulk messages. Bulk messages are defined as ordered messages to one receiver.

Body parameter

{
  "to": "+1233423454",
  "from": "+1233423454",
  "messagePurpose": "promotion",
  "rateType": "promotion",
  "channel": "viber",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

Parameters

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

Example responses

202 Response

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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 response after the server has accepted the request BulkMessageResponse
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 The default response in case of any other error. Please check the error object for details Problem

Service IDs

List all Service IDs configured for your API account.

List Service IDs

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/viber \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/viber 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/conversations/v3/configurations/channels/viber',
{
  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/conversations/v3/configurations/channels/viber',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/viber', 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/conversations/v3/configurations/channels/viber', 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/conversations/v3/configurations/channels/viber");
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/conversations/v3/configurations/channels/viber", data)
    req.Header = headers

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

GET /configurations/channels/viber

List all Service ID configurations available to your API account

Example responses

200 Response

[
  {
    "channel": "viber",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "serviceId": "1234"
    },
    "name": "Your Company",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

403 Response

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

Responses

Status Meaning Description Schema
200 OK A list of Viber channel configurations ViberChannelResponses
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Read a configuration

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id} \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-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/conversations/v3/configurations/channels/viber/service-ids/{service-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/conversations/v3/configurations/channels/viber/service-ids/{service-id}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-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/conversations/v3/configurations/channels/viber/service-ids/{service-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/conversations/v3/configurations/channels/viber/service-ids/{service-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/conversations/v3/configurations/channels/viber/service-ids/{service-id}", data)
    req.Header = headers

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

GET /configurations/channels/viber/service-ids/{service-id}

Returns the specific channel configuration

Parameters

Name In Type Required Description
service-id path integer true The Service ID used for a Viber Channel.

Example responses

200 Response

{
  "channel": "viber",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "serviceId": "1234"
  },
  "name": "Your Company",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

403 Response

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

Responses

Status Meaning Description Schema
200 OK A Viber channel configuration ViberChannelResponse
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Callback configuration

In this section, we guide you on how to configure the callbacks on a per-channel basis.

Update the callback

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks', 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/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/channels/viber/service-ids/{service-id}/callbacks", data)
    req.Header = headers

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

PUT /configurations/channels/viber/service-ids/{service-id}/callbacks

Update the callback settings of a specific Service ID.

Body parameter

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

Parameters

Name In Type Required Description
body body ChannelCallback false none
service-id path integer true The Service ID used for a Viber Channel.

Example responses

200 Response

{
  "channel": "viber",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "serviceId": "1234"
  },
  "name": "Your Company",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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
200 OK A Viber channel configuration ViberChannelResponse
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 The default response in case of any other error. Please check the error object for details Problem

Schemas

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

MessageResponse

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

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none A global unique Message Id reference
timestamp string(date-time) true none A point in time when the API confirms that the message request was accepted

BulkMessageResponse

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

Properties

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

MessageRequest

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "viber",
  "messagePurpose": "promotion",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}

The message you would like to send. Either rate type or message purpose must be set

Properties

Name Type Required Restrictions Description
to string true none The message's recipient
The format depends on the specific channel
from string true none The Viber service id the message origins from
messagePurpose string false none The alias for the message's rate type
rateType string false none The rate type of the message. Note Since Viber has lifted the service types, this
affects the rate for each message. Also, the potential content that can be sent (see table above)
channel string true none The channel selected for delivery.
overrides object false none Overrides of defaults for this message
» 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.
context string false none The context for this particular message
content any false none none

oneOf

Name Type Required Restrictions Description
» anonymous ViberTextContent false none none

xor

Name Type Required Restrictions Description
» anonymous ViberImageContent false none none

xor

Name Type Required Restrictions Description
» anonymous ViberFileContent false none A file content wrapper for Viber

xor

Name Type Required Restrictions Description
» anonymous ViberComponentsContent false none none
Enumerated values
Property Value
messagePurpose promotion
messagePurpose transaction
messagePurpose session
rateType promotion
rateType transaction
rateType session
channel viber

BulkMessageRequest

{
  "to": "+1233423454",
  "from": "+1233423454",
  "messagePurpose": "promotion",
  "rateType": "promotion",
  "channel": "viber",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

The bulk of messages you would like to send. Either rate type or message purpose must be set

Properties

Name Type Required Restrictions Description
to string true none The message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
messagePurpose string false none The alias for the message's rate type
rateType string false none The rate type of the message. Note Since Viber has lifted the service types, this
affects the rate for each message. Also the potential content that can be sent (see table above)
channel string true none The channel selected for delivery.
messages [oneOf] true none none

oneOf

Name Type Required Restrictions Description
» anonymous ViberTextContent false none none

xor

Name Type Required Restrictions Description
» anonymous ViberImageContent false none none

xor

Name Type Required Restrictions Description
» anonymous ViberFileContent false none A file content wrapper for Viber

xor

Name Type Required Restrictions Description
» anonymous ViberVideoContent false none none

xor

Name Type Required Restrictions Description
» anonymous ViberComponentsContent false none none
Enumerated values
Property Value
messagePurpose promotion
messagePurpose transaction
messagePurpose session
rateType promotion
rateType transaction
rateType session
channel viber

ViberTextContent

{
  "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

ViberTextBody

{
  "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

ViberImageContent

{
  "contentType": "image",
  "image": {
    "url": "string"
  }
}

Properties

Name Type Required Restrictions Description
contentType string false none none
image ViberImage false none none
Enumerated values
Property Value
contentType image

ViberVideoContent

{
  "contentType": "video",
  "video": {
    "url": "string",
    "thumbnailUrl": "string",
    "type": "3gp",
    "filesize": 0,
    "duration": 0
  }
}

Properties

Name Type Required Restrictions Description
contentType string false none none
video ViberVideo false none Viber video specification
Enumerated values
Property Value
contentType video

ViberVideoBody

{
  "type": "video",
  "video": {
    "url": "string",
    "thumbnailUrl": "string",
    "type": "3gp",
    "filesize": 0,
    "duration": 0
  }
}

Properties

Name Type Required Restrictions Description
type string false none none
video ViberVideo false none Viber video specification
Enumerated values
Property Value
type video

ViberImageBody

{
  "type": "image",
  "image": {
    "url": "string"
  }
}

Properties

Name Type Required Restrictions Description
type string false none none
image ViberImage false none none
Enumerated values
Property Value
type image

ViberFileContent

{
  "contentType": "file",
  "file": {
    "url": "string",
    "filename": "string",
    "type": "doc"
  }
}

A file content wrapper for Viber

Properties

Name Type Required Restrictions Description
contentType string false none Defines the content type. Always file
file ViberFile false none A Viber file specification
Enumerated values
Property Value
contentType file

ViberFileBody

{
  "contentType": "file",
  "file": {
    "url": "string",
    "filename": "string",
    "type": "doc"
  }
}

A file content wrapper for Viber

Properties

Name Type Required Restrictions Description
contentType string false none Defines the content type. Always file
file ViberFile false none A Viber file specification
Enumerated values
Property Value
contentType file

ViberButtonBody

{
  "contentType": "button",
  "button": {
    "caption": "string",
    "url": "string"
  }
}

Properties

Name Type Required Restrictions Description
contentType string false none none
button ViberButton false none none
Enumerated values
Property Value
contentType button

ViberComponentsContent

{
  "contentType": "components",
  "components": {
    "body": [
      {
        "type": "text",
        "text": "string"
      }
    ]
  }
}

Properties

Name Type Required Restrictions Description
contentType string false none none
components object false none none
» body [anyOf] false none none

anyOf

Name Type Required Restrictions Description
»» anonymous ViberTextBody false none none

or

Name Type Required Restrictions Description
»» anonymous ViberImageBody false none none

or

Name Type Required Restrictions Description
»» anonymous ViberFileBody false none A file content wrapper for Viber

or

Name Type Required Restrictions Description
»» anonymous ViberVideoBody false none none

or

Name Type Required Restrictions Description
»» anonymous ViberButtonBody false none none
Enumerated values
Property Value
contentType components

ViberImage

{
  "url": "string"
}

Properties

Name Type Required Restrictions Description
url string false none A publicly available URL of the image. The image URL will be used on the app to provide the user with the file.

ViberFile

{
  "url": "string",
  "filename": "string",
  "type": "doc"
}

A Viber file specification

Properties

Name Type Required Restrictions Description
url string true none A publicly available URL of the file. The file URL will be used on the app to provide the user with the file.
filename string true none The 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 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

ViberVideo

{
  "url": "string",
  "thumbnailUrl": "string",
  "type": "3gp",
  "filesize": 0,
  "duration": 0
}

Viber video specification

Properties

Name Type Required Restrictions Description
url string true none Public available URL of the video. The video URL will be used on the app to provide the user with the video.
thumbnailUrl string true none Public available URL of a thumbnail picture of the video.
type string false none This parameter can be set to specify the video type.
If not present, the video type is deducted from the URL given.
filesize integer true none Filesize in MB
duration integer true none Duration of the video in seconds
Enumerated values
Property Value
type 3gp
type m4v
type mov
type mp4

ViberButton

{
  "caption": "string",
  "url": "string"
}

Properties

Name Type Required Restrictions Description
caption string false none none
url string false none none

ViberChannelResponse

{
  "channel": "viber",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "serviceId": "1234"
  },
  "name": "Your Company",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id object false none The definition of the Viber Service id
» serviceId string false none none
config object false none none
» serviceType string true none none
Enumerated values
Property Value
serviceType session
serviceType two-way
serviceType one-way

ViberChannelResponses

[
  {
    "channel": "viber",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "serviceId": "1234"
    },
    "name": "Your Company",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
id object false none The definition of the Viber Service id
» serviceId string false none none
config object false none none
» serviceType string true none none
Enumerated values
Property Value
serviceType session
serviceType two-way
serviceType one-way

ChannelCallback

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [string] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11

SMS

Version: v3.0

Specification Release Notes Other versions

The Conversations API allows you to easily reach out and communicate with your clients via 2-way SMS.

Channel specific pre-conditions

  • 2-way SMS : Please contact us to get the details for the 2-way SMS setup

Base URLs

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/conversations/v3/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

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

const inputBody = '{
  "to": "+123234234",
  "from": "545345345",
  "channel": "sms",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/messages", data)
    req.Header = headers

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

POST /messages

Send messages via this path.

Body parameter

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "sms",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}

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",
  "timestamp": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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 response after the server has accepted the request 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 The default response in case of any other error. Please check the error object for details Problem

Send a bulk message

Code samples

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

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

const inputBody = '{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "sms",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/bulks", data)
    req.Header = headers

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

POST /bulks

Send bulk messages. Bulk messages are defined as ordered messages to one receiver.

Body parameter

{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "sms",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

Parameters

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

Example responses

202 Response

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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 response after the server has accepted the request BulkMessageResponse
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 The default response in case of any other error. Please check the error object for details Problem

Inbound Phone Numbers

List all phone numbers configured as Inbound (aka 2-way) Phone Numbers.

List Phone Numbers

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/sms \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/sms 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/conversations/v3/configurations/channels/sms',
{
  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/conversations/v3/configurations/channels/sms',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/sms', 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/conversations/v3/configurations/channels/sms', 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/conversations/v3/configurations/channels/sms");
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/conversations/v3/configurations/channels/sms", data)
    req.Header = headers

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

GET /configurations/channels/sms

List all Inbound Phone Number configurations available to your API account

Example responses

200 Response

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

403 Response

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

Responses

Status Meaning Description Schema
200 OK A list of SMS channel configurations SMSChannelResponses
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Read a configuration

Code samples

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

GET https://api.tyntec.com/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/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/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}", data)
    req.Header = headers

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

GET /configurations/channels/sms/phone-numbers/{phone-number}

Returns the specific inbound configuration

Parameters

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

Example responses

200 Response

{
  "channel": "sms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

403 Response

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

Responses

Status Meaning Description Schema
200 OK A list of SMS channel configurations SMSChannelResponse
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Callback configuration

In this section, we guide you on how to configure the callbacks on a per-channel basis.

At the moment this is only supported for Inbound Phone Numbers.

In case you need to route Message Status events for outbound SMS differently, please use the overrides.messageStatusUrl property.

Update the callback

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks', 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/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/channels/sms/phone-numbers/{phone-number}/callbacks", data)
    req.Header = headers

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

PUT /configurations/channels/sms/phone-numbers/{phone-number}/callbacks

Update the callback settings for a specific inbound phone number. Note The complete object must be provided

Body parameter

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

Parameters

Name In Type Required Description
body body ChannelCallback false none
phone-number path integer true Phone number used for SMS.

Example responses

200 Response

{
  "channel": "sms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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
200 OK A list of SMS channel configurations SMSChannelResponse
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 The default response in case of any other error. Please check the error object for details Problem

Schemas

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

MessageResponse

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

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none A global unique Message Id reference
timestamp string(date-time) true none A point in time when the API confirms that the message request was accepted

BulkMessageResponse

{
  "bulkId": "string",
  "messageIds": [
    "string"
  ]
}

Properties

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

MessageRequest

{
  "to": "+123234234",
  "from": "545345345",
  "channel": "sms",
  "content": {
    "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 message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
overrides object false none Overrides of defaults for this message
» 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.
context string false none The context for this particular message
content SMSContent false none none
Enumerated values
Property Value
channel sms

BulkMessageRequest

{
  "to": "+1233423454",
  "from": "+1233423454",
  "channel": "sms",
  "messages": [
    {
      "contentType": "text",
      "text": "string"
    },
    {
      "contentType": "text",
      "text": "string"
    }
  ]
}

The bulk of messages you would like to send

Properties

Name Type Required Restrictions Description
to string true none The message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
messages [SMSContent] true none none
Enumerated values
Property Value
channel sms

SMSContent

{
  "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

SMSChannelResponse

{
  "channel": "sms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

SMSChannelResponses

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

ChannelCallback

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [string] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11

MMS

Version: v3.0

Specification Release Notes Other versions

The Conversations API allows you to easily reach out and communicate with your clients via MMS.

Base URLs

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/conversations/v3/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

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

const inputBody = '{
  "to": "155598765432",
  "from": "15551234567",
  "channel": "mms",
  "content": {
    "contentType": "image",
    "image": {
      "url": "https://test.com/image.jpg",
      "caption": "Look at this!"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/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/conversations/v3/messages", data)
    req.Header = headers

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

POST /messages

Send messages via this path.

Body parameter

{
  "to": "155598765432",
  "from": "15551234567",
  "channel": "mms",
  "content": {
    "contentType": "image",
    "image": {
      "url": "https://test.com/image.jpg",
      "caption": "Look at this!"
    }
  }
}

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",
  "timestamp": "2019-08-24T14:15:22Z"
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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 response after the server has accepted the request 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 The default response in case of any other error. Please check the error object for details Problem

MMS Phone Numbers

List all MMS Phone Numbers configured for your API account.

List MMS Phone Numbers

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/mms \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/mms 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/conversations/v3/configurations/channels/mms',
{
  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/conversations/v3/configurations/channels/mms',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/mms', 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/conversations/v3/configurations/channels/mms', 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/conversations/v3/configurations/channels/mms");
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/conversations/v3/configurations/channels/mms", data)
    req.Header = headers

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

GET /configurations/channels/mms

List all MMS Phone Number configurations available to your API account

Example responses

200 Response

[
  {
    "channel": "mms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "15559876543"
    },
    "name": "your name",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::dispatched"
      ]
    }
  }
]

403 Response

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

Responses

Status Meaning Description Schema
200 OK A list of Mms channel configurations MmsChannelResponses
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Callback configuration

In this section, we guide you on how to configure the callbacks on a per-channel basis.

Update the callback

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks', 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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks", data)
    req.Header = headers

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

PUT /configurations/channels/mms/phone-numbers/{mms-phone-number}/callbacks

Update the callback settings of a specific Mms Phone Number

Body parameter

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

Parameters

Name In Type Required Description
body body ChannelCallback false none
mms-phone-number path string true MMS Phone number used for MMS messaging.

Example responses

200 Response

{
  "channel": "mms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "15559876543"
  },
  "name": "your name",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::dispatched"
    ]
  }
}

400 Response

{
  "status": 400,
  "violations": [
    {
      "field": "validate.request.content.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
200 OK A MMS Phone Number configuration MmsChannelResponse
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 The default response in case of any other error. Please check the error object for details Problem

MMS Phone Number

Read a configuration

Code samples

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

GET https://api.tyntec.com/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-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/conversations/v3/configurations/channels/mms/phone-numbers/{mms-phone-number}", data)
    req.Header = headers

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

GET /configurations/channels/mms/phone-numbers/{mms-phone-number}

Returns the specific channel configuration

Parameters

Name In Type Required Description
mms-phone-number path string true MMS Phone number used for MMS messaging.

Example responses

200 Response

{
  "channel": "mms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "15559876543"
  },
  "name": "your name",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::dispatched"
    ]
  }
}

403 Response

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

Responses

Status Meaning Description Schema
200 OK A MMS Phone Number configuration MmsChannelResponse
403 Forbidden You attempting to use a number that is not assigned to your account Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Schemas

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

MessageResponse

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

Properties

Name Type Required Restrictions Description
messageId string(uuid) true none A global unique Message Id reference
timestamp string(date-time) true none A point in time when the API confirms that the message request was accepted

MessageRequest

{
  "to": "155598765432",
  "from": "15551234567",
  "channel": "mms",
  "content": {
    "contentType": "image",
    "image": {
      "url": "https://test.com/image.jpg",
      "caption": "Look at this!"
    }
  }
}

The message you would like to send

Properties

Name Type Required Restrictions Description
to string true none The message's recipient
The format depends on the specific channel
from string true none The sender of the messages. The format depends on the specific channel.
channel string true none The channel selected for delivery.
overrides object false none Overrides of defaults for this message
» 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.
context string false none The context for this particular message
content any false none none

oneOf

Name Type Required Restrictions Description
» anonymous MmsTextContent false none A plain text message

xor

Name Type Required Restrictions Description
» anonymous MmsImageContent false none none
Enumerated values
Property Value
channel mms

MmsTextContent

{
  "contentType": "text",
  "text": "string"
}

A plain text message

Properties

Name Type Required Restrictions Description
contentType string true none Determines the type of the message. Always text.
text string true none Text to be sent
Enumerated values
Property Value
contentType text

MmsImageContent

{
  "contentType": "image",
  "image": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "url": "string",
    "caption": "string"
  }
}

Properties

Name Type Required Restrictions Description
contentType string false none none
image MmsImage false none One of both properties url or id must be set
Enumerated values
Property Value
contentType image

MmsImage

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "url": "string",
  "caption": "string"
}

One of both properties url or id must be set

Properties

Name Type Required Restrictions Description
id string(uuid) false none The media id of previously uploaded media
url string false none the url of the location where the media is stored
caption string false none none

MmsChannelResponse

{
  "channel": "mms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "15559876543"
  },
  "name": "your name",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::dispatched"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

MmsChannelResponses

[
  {
    "channel": "mms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "15559876543"
    },
    "name": "your name",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::dispatched"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
id object false none The definition of the Phone Number Id
» phoneNumber string false none none

ChannelCallback

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [string] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11

Configurations

Version: v3.4

Specification Release Notes Other versions

The Configurations allows you to set up certain parts of settings on account or channel level.

Included are callback settings, credentials (where appropriate), and a signature for incoming events.

Credentials

Some channels require you to provide tyntec with credentials. The Conversations API allows you to configure these credentials via the API directly

Signature

Validating that the message content hasn't been tampered is a crucial part of a secure message exchange.

The Conversations API can provide you with a message signature that encrypts the actual event content with a keyed-hash message authentication code HMAC.

The signature is transferred in the header x-signature as a Base64 URL encoded value.

As a preparation, both parties need to align on

  • the algorithm used
  • the shared secret

With this information, the request timestamp (header x-request-timestamp), the signature version (header x-signature-version), and the actual event, we calculate the signature.

If you want to check if the message has been tampered on the transmission, you need to calculate the signature yourself and compare it with the signature provided in the header x-signature.

The following pseudo-code examples show you how to calculate the signature

Signature version: V1.0

  secret = "secret key"
  algorithm = "SHA256"

  requestTimestamp = request.headers["x-request-timestamp"]
  body = request.body // String representation without any modifications

  data = requestTimestamp + "\n" + body
  signature_bytes = HMAC(algorithm, secret, data)

  tt_signature = request.headers["x-signature"]
  if (Base64URLEncode(signature_bytes) == tt_signature)
  then
    echo "Verified"
  else
    echo "Tampered!"
  fi

We advise as well to verify if the request timestamp is not too old (a couple of minutes at most) and discard the message otherwise.

Callback Overiding Rules

We do support specifying callback configurations on the API account level (global) and channel id specific level (local).

On both levels only a part of the configuration must be present. They will be merged into an effective callback configuration.

It follows the rule that the local configuration overrides the global configuration on the specified parts.

For example for the callback configurations on the global level

callbackVersion: 2.11
inboundMessage: http://my.server.com/inbound
messageStatus: http://my.server.com/status
eventFilter: []

and the Viber Service ID 123:

inboundMessage: http://my.server.com/inbound-viber
eventFilter:
 - MessageStatus::accepted
 - MessageStatus::channelFailed

would result in the effective configuration for the Viber Service ID 123

callbackVersion: 2.11
inboundMessage: http://my.server.com/inbound-viber
messageStatus: http://my.server.com/status
eventFilter:
 - MessageStatus::accepted
 - MessageStatus::channelFailed

and for any other channel:

callbackVersion: 2.11
inboundMessage: http://my.server.com/inbound
messageStatus: http://my.server.com/status
eventFilter: []

Scopes

Account scopes

The API account can have the following scopes:

Scope Description
callbacks:read Grants read access to the account level callbacks
callbacks:write Grants write access to the account level callbacks
credentials:read Grants read access to the account level credentials, eg media credentials
credentials:write Grants write access to the account level credentials, eg media credentials
channels:read Grants read access to assigned channels
media:read Grants read access to media files (inbound/outbound)
media:write Grants write access to outbound media files

Channel scopes

Channel resources can have the following scopes:

Scope Description Available on
callbacks:read Grants read access to channel-level callbacks SMS Viber WhatsApp
callbacks:write Grants write access to channel-level callbacks SMS Viber WhatsApp
credentials:read Grants read access to the channel's credentials -
credentials:write Grants write access to the channel's credentials -
messages:read Grants read access to messages of a channel -
messages:write Grants access to send messages via a channel SMS Viber WhatsApp
profile:read Grants read access to a channel's profile. eg WhatsApp WhatsApp
profile:write Grants write access to a channel's profile. eg WhatsApp WhatsApp
templates:read Grants read access to a channel's templates. eg WhatsApp WhatsApp
templates:write Grants write access to a channel's templates. eg WhatsApp WhatsApp

Base URLs

API Account Configurations

API Account configurations allow you to configure settings global to your API account.

Get account configuration

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations 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/conversations/v3/configurations',
{
  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/conversations/v3/configurations',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations', 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/conversations/v3/configurations', 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/conversations/v3/configurations");
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/conversations/v3/configurations", data)
    req.Header = headers

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

GET /configurations

Returns the configuration of the API account

Example responses

200 Response

{
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.12",
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    },
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "config": {
    "mediaCredentials": {
      "type": "oauth2",
      "oauth2": {
        "clientId": "string",
        "clientSecret": "string",
        "url": "string"
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK The configuration of the account AccountConfiguration

Update the callback

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/callbacks \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/callbacks HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "callbackVersion": "2.12",
  "signature": {
    "secret": "stringst",
    "method": "HS256"
  },
  "header": {
    "key": "string",
    "value": "stringst"
  },
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/callbacks',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/callbacks',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/callbacks', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/callbacks', 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/conversations/v3/configurations/callbacks");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/callbacks", data)
    req.Header = headers

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

PUT /configurations/callbacks

Update the callback settings of the account. Note The complete object must be provided

Body parameter

{
  "callbackVersion": "2.12",
  "signature": {
    "secret": "stringst",
    "method": "HS256"
  },
  "header": {
    "key": "string",
    "value": "stringst"
  },
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

Parameters

Name In Type Required Description
body body Callback false none

Example responses

200 Response

{
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.12",
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    },
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "config": {
    "mediaCredentials": {
      "type": "oauth2",
      "oauth2": {
        "clientId": "string",
        "clientSecret": "string",
        "url": "string"
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK The configuration of the account AccountConfiguration

Update the media credentials

Code samples

# You can also use wget
curl -X PUT https://api.tyntec.com/conversations/v3/configurations/mediaCredentials \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

PUT https://api.tyntec.com/conversations/v3/configurations/mediaCredentials HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json
apikey: API_KEY

const inputBody = '{
  "type": "oauth2",
  "oauth2": {
    "clientId": "string",
    "clientSecret": "string",
    "url": "string"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json',
  'apikey':'API_KEY'

};

fetch('https://api.tyntec.com/conversations/v3/configurations/mediaCredentials',
{
  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/json',
  'apikey' => 'API_KEY'
}

result = RestClient.put 'https://api.tyntec.com/conversations/v3/configurations/mediaCredentials',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.put('https://api.tyntec.com/conversations/v3/configurations/mediaCredentials', 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('PUT','https://api.tyntec.com/conversations/v3/configurations/mediaCredentials', 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/conversations/v3/configurations/mediaCredentials");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PUT");
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("PUT", "https://api.tyntec.com/conversations/v3/configurations/mediaCredentials", data)
    req.Header = headers

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

PUT /configurations/mediaCredentials

Update the media credentials of the account.

Body parameter

{
  "type": "oauth2",
  "oauth2": {
    "clientId": "string",
    "clientSecret": "string",
    "url": "string"
  }
}

Parameters

Name In Type Required Description
body body MediaCredentials false none

Example responses

200 Response

{
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.12",
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    },
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "config": {
    "mediaCredentials": {
      "type": "oauth2",
      "oauth2": {
        "clientId": "string",
        "clientSecret": "string",
        "url": "string"
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK The configuration of the account AccountConfiguration

Remove the media credentials

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/v3/configurations/mediaCredentials \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

DELETE https://api.tyntec.com/conversations/v3/configurations/mediaCredentials 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/conversations/v3/configurations/mediaCredentials',
{
  method: 'DELETE',

  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.delete 'https://api.tyntec.com/conversations/v3/configurations/mediaCredentials',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/v3/configurations/mediaCredentials', 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('DELETE','https://api.tyntec.com/conversations/v3/configurations/mediaCredentials', 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/conversations/v3/configurations/mediaCredentials");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
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("DELETE", "https://api.tyntec.com/conversations/v3/configurations/mediaCredentials", data)
    req.Header = headers

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

DELETE /configurations/mediaCredentials

Remove the media credentials of the account.

Example responses

200 Response

{
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.12",
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    },
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "config": {
    "mediaCredentials": {
      "type": "oauth2",
      "oauth2": {
        "clientId": "string",
        "clientSecret": "string",
        "url": "string"
      }
    }
  }
}

Responses

Status Meaning Description Schema
200 OK The configuration of the account AccountConfiguration

Channel Configurations

Channel Account configurations allow you to configure settings local to a specific channel.

A channel here is referred to as the identity you use to send messages to your clients.

List all channels

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels 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/conversations/v3/configurations/channels',
{
  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/conversations/v3/configurations/channels',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels', 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/conversations/v3/configurations/channels', 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/conversations/v3/configurations/channels");
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/conversations/v3/configurations/channels", data)
    req.Header = headers

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

GET /configurations/channels

List all channels available to your API account

Example responses

200 Response

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Responses

Status Meaning Description Schema
200 OK A list of all channel configurations AllChannelResponses

List all SMS channels

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/sms \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/sms 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/conversations/v3/configurations/channels/sms',
{
  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/conversations/v3/configurations/channels/sms',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/sms', 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/conversations/v3/configurations/channels/sms', 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/conversations/v3/configurations/channels/sms");
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/conversations/v3/configurations/channels/sms", data)
    req.Header = headers

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

GET /configurations/channels/sms

List all Inbound SMS channels available to your API account

Example responses

200 Response

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Responses

Status Meaning Description Schema
200 OK A list of SMS channel configurations SMSChannelResponses

List all Mms channels

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/mms \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/mms 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/conversations/v3/configurations/channels/mms',
{
  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/conversations/v3/configurations/channels/mms',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/mms', 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/conversations/v3/configurations/channels/mms', 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/conversations/v3/configurations/channels/mms");
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/conversations/v3/configurations/channels/mms", data)
    req.Header = headers

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

GET /configurations/channels/mms

List all Mms channels available to your API account

Example responses

200 Response

[
  {
    "channel": "mms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "15559876543"
    },
    "name": "your name",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::dispatched"
      ]
    }
  }
]

Responses

Status Meaning Description Schema
200 OK A list of Mms channel configurations MmsChannelResponses

List all Viber channels

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/configurations/channels/viber \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY'

GET https://api.tyntec.com/conversations/v3/configurations/channels/viber 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/conversations/v3/configurations/channels/viber',
{
  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/conversations/v3/configurations/channels/viber',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/viber', 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/conversations/v3/configurations/channels/viber', 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/conversations/v3/configurations/channels/viber");
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/conversations/v3/configurations/channels/viber", data)
    req.Header = headers

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

GET /configurations/channels/viber

List all Viber channels available to your API account

Example responses

200 Response

[
  {
    "channel": "viber",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "serviceId": "1234"
    },
    "name": "Your Company",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Responses

Status Meaning Description Schema
200 OK A list of Viber channel configurations ViberChannelResponses

List all WhatsApp channels

Code samples

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

GET https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp 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/conversations/v3/configurations/channels/whatsapp',
{
  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/conversations/v3/configurations/channels/whatsapp',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/configurations/channels/whatsapp', 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/conversations/v3/configurations/channels/whatsapp', 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/conversations/v3/configurations/channels/whatsapp");
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/conversations/v3/configurations/channels/whatsapp", data)
    req.Header = headers

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

GET /configurations/channels/whatsapp

List all WhatsApp channels available to your API account

Example responses

200 Response

[
  {
    "channel": "whatsapp",
    "scopes": [
      "messages:read",
      "profile:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Responses

Status Meaning Description Schema
200 OK A list of Whatsapp channel configurations WhatsAppChannelResponses

Schemas

AccountConfiguration

{
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.12",
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    },
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "config": {
    "mediaCredentials": {
      "type": "oauth2",
      "oauth2": {
        "clientId": "string",
        "clientSecret": "string",
        "url": "string"
      }
    }
  }
}

A configuration of an API account

Properties

Name Type Required Restrictions Description
scopes [AccountScopes] false none [Scopes available to your account.]
callback Callback false none A configuration of callbacks to your system
config DetailedAccountConfig false none none

AccountScopes

"channels:read"

Scopes available to your account.

Properties

Name Type Required Restrictions Description
anonymous string false none Scopes available to your account.
Enumerated values
Property Value
anonymous channels:read
anonymous callbacks:read
anonymous callbacks:write
anonymous credentials:read
anonymous credentials:write
anonymous media:read
anonymous media:write

Callback

{
  "callbackVersion": "2.12",
  "signature": {
    "secret": "stringst",
    "method": "HS256"
  },
  "header": {
    "key": "string",
    "value": "stringst"
  },
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
signature Signature false none A signature configuration for incoming events. Can be disabled by setting the
signature property to empty.
header Header false none An additional custom header to be sent with the event transmission. Can be used for setting
authentication tokens, or similar.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [EventTypes] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11
callbackVersion 2.12

EventTypes

"MessageStatus::accepted"

Determines which kind of event is emitted by the API

Properties

Name Type Required Restrictions Description
anonymous string false none Determines which kind of event is emitted by the API
Enumerated values
Property Value
anonymous MessageStatus::accepted
anonymous MessageStatus::channelFailed
anonymous MessageStatus::deleted
anonymous MessageStatus::delivered
anonymous MessageStatus::failed
anonymous MessageStatus::seen
anonymous MessageStatus::unknown

Signature

{
  "secret": "stringst",
  "method": "HS256"
}

A signature configuration for incoming events. Can be disabled by setting the signature property to empty.

Properties

Name Type Required Restrictions Description
secret string true none A shared secret key
method string true none A cryptographic algorithm used for signature calculation
Enumerated values
Property Value
method HS256
method HS512

Header

{
  "key": "string",
  "value": "stringst"
}

An additional custom header to be sent with the event transmission. Can be used for setting authentication tokens, or similar.

Properties

Name Type Required Restrictions Description
key string true none The name of the HTTP header
value string true none The value of the HTTP header

DetailedAccountConfig

{
  "mediaCredentials": {
    "type": "oauth2",
    "oauth2": {
      "clientId": "string",
      "clientSecret": "string",
      "url": "string"
    }
  }
}

Properties

Name Type Required Restrictions Description
mediaCredentials MediaCredentials false none Credentials to download media from your remote service

MediaCredentials

{
  "type": "oauth2",
  "oauth2": {
    "clientId": "string",
    "clientSecret": "string",
    "url": "string"
  }
}

Credentials to download media from your remote service

Properties

oneOf

Name Type Required Restrictions Description
anonymous OAuth2MediaCredentials false none Oauth 2 credentials. Only supports client secret flow

xor

Name Type Required Restrictions Description
anonymous BasicMediaCredentials false none none

OAuth2MediaCredentials

{
  "type": "oauth2",
  "oauth2": {
    "clientId": "string",
    "clientSecret": "string",
    "url": "string"
  }
}

Oauth 2 credentials. Only supports client secret flow

Properties

Name Type Required Restrictions Description
type string false none Determines the type of credentials. Always oauth2.
oauth2 object false none none
» clientId string true none none
» clientSecret string true none none
» url string true none none
Enumerated values
Property Value
type oauth2

BasicMediaCredentials

{
  "type": "basic",
  "basic": {
    "username": "string",
    "password": "string"
  }
}

Properties

Name Type Required Restrictions Description
type string false none Determines the type of credentials. Always basic.
basic object false none none
» username string true none none
» password string true none none
Enumerated values
Property Value
type basic

AllChannelResponses

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

anyOf

Name Type Required Restrictions Description
anonymous SMSChannelResponse false none none

or

Name Type Required Restrictions Description
anonymous MmsChannelResponse false none none

or

Name Type Required Restrictions Description
anonymous ViberChannelResponse false none none

or

Name Type Required Restrictions Description
anonymous WhatsAppChannelResponse false none none

ChannelResponse

{
  "channel": "string",
  "scopes": [
    "channels:read"
  ],
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "eventFilter": []
  },
  "name": "string"
}

General channel configuration

Properties

Name Type Required Restrictions Description
channel string false none none
scopes [ChannelScopes] false none [Scopes available to a channel.]
callback ChannelCallback false none A configuration of callbacks to your system
name string false none none

ChannelScopes

"channels:read"

Scopes available to a channel.

Properties

Name Type Required Restrictions Description
anonymous string false none Scopes available to a channel.
Enumerated values
Property Value
anonymous channels:read
anonymous callbacks:read
anonymous callbacks:write
anonymous media:read
anonymous media:write

ChannelCallback

{
  "callbackVersion": "2.11",
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "eventFilter": []
}

A configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
callbackVersion string false none The event version to be used.
inboundMessageUrl string false none A webhook for events related to inbound messages
messageStatusUrl string false none A webhook for events related to message status changes
eventFilter [EventTypes] false none A list of status events to listen to. If empty, all events are submitted.
Enumerated values
Property Value
callbackVersion 2.11

MmsChannelResponses

[
  {
    "channel": "mms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "15559876543"
    },
    "name": "your name",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::dispatched"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
anonymous [MmsChannelResponse] false none none

MmsChannelResponse

{
  "channel": "mms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "15559876543"
  },
  "name": "your name",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::dispatched"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id PhoneNumberId false none The definition of the Phone Number Id

SMSChannelResponses

[
  {
    "channel": "sms",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
anonymous [SMSChannelResponse] false none none

SMSChannelResponse

{
  "channel": "sms",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id PhoneNumberId false none The definition of the Phone Number Id

WhatsAppChannelResponses

[
  {
    "channel": "whatsapp",
    "scopes": [
      "messages:read",
      "profile:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "phoneNumber": "12341234"
    },
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
anonymous [WhatsAppChannelResponse] false none none

WhatsAppChannelResponse

{
  "channel": "whatsapp",
  "scopes": [
    "messages:read",
    "profile:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "phoneNumber": "12341234"
  },
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id PhoneNumberId false none The definition of the Phone Number Id

ViberChannelResponses

[
  {
    "channel": "viber",
    "scopes": [
      "messages:read",
      "callbacks:write",
      "callbacks:read"
    ],
    "id": {
      "serviceId": "1234"
    },
    "name": "Your Company",
    "callback": {
      "callbackVersion": "2.11",
      "inboundMessageUrl": "https://your.server.com/inbound",
      "messageStatusUrl": "https://your.server.com/status",
      "eventFilter": [
        "MessageStatus::accepted",
        "MessageStatus::delivered"
      ]
    }
  }
]

Properties

Name Type Required Restrictions Description
anonymous [ViberChannelResponse] false none none

ViberChannelResponse

{
  "channel": "viber",
  "scopes": [
    "messages:read",
    "callbacks:write",
    "callbacks:read"
  ],
  "id": {
    "serviceId": "1234"
  },
  "name": "Your Company",
  "callback": {
    "callbackVersion": "2.11",
    "inboundMessageUrl": "https://your.server.com/inbound",
    "messageStatusUrl": "https://your.server.com/status",
    "eventFilter": [
      "MessageStatus::accepted",
      "MessageStatus::delivered"
    ]
  }
}

Properties

Name Type Required Restrictions Description
id ServiceId false none The definition of the Viber Service id
config ViberChannelConfigs false none none

PhoneNumberId

{
  "phoneNumber": "string"
}

The definition of the Phone Number Id

Properties

Name Type Required Restrictions Description
phoneNumber string false none none

ServiceId

{
  "serviceId": "string"
}

The definition of the Viber Service id

Properties

Name Type Required Restrictions Description
serviceId string false none none

ViberChannelConfigs

{
  "serviceType": "session"
}

Properties

Name Type Required Restrictions Description
serviceType string true none none
Enumerated values
Property Value
serviceType session
serviceType two-way
serviceType one-way

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

Webhook Events V2

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 Configuration.

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

The server address of tyntec, the events originate from

Received messages

Events emitted when the recipient of the message replies or deletes a previously sent message.

MoMessage (Basic)

A 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",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}
Properties
Name Type Required Description
event string true Determines which type of event is sent. Always MoMessage
channel string true The channel that triggered the event.
receivedAt string(date-time) false The 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 The point in time when the message was received
messageId string true A message ID reference
from string true The sender of the message
to string false The receiver. The format is channel-specific
groupId string false The group ID from which the event originates. Only present if the message was sent into a group.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL 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
contentType reaction
contentType unknown
type image
type document
type audio
type voice
type video

MoMessage (SMS)

A 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 The 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 customers.
»» 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)

A 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 The channel that triggered the event.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp Whatsapp false Details specific to the WhatsApp channel
» senderName string false The name of the sender, set in his or her profile
Enumerated values
Property Value
channel whatsapp
contentType text
contentType media
contentType location
contentType contacts
contentType reaction
contentType unknown
type image
type document
type audio
type voice
type video

MoMessage (Viber)

A 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 The channel that triggered the event.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
Enumerated values
Property Value
channel viber
contentType text
contentType media
contentType location
contentType contacts
contentType reaction
contentType unknown
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 The channel that triggered the event.
timestamp string(date-time) true The point in time when the message was received
messageId string true A message ID reference
from string false The sender of the message
to string false The receiver. The format is channel-specific
groupId string false The 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 The 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. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp WhatsAppPostBack false Postback data for a WhatsApp quick reply button
» text string false The caption of the button that was clicked
» title string false The title of the interactive item clicked
» description string false The 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",
        "productName": "product 1",
        "description": "short description",
        "quantity": 123,
        "itemPrice": 123.22,
        "currency": "EUR"
      },
      {
        "productId": "24-1111134-sdfk",
        "productName": "product 2",
        "description": "short description",
        "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 The channel that triggered the event.
timestamp string(date-time) true The point in time when the message was received
messageId string true A message ID reference
from string false The sender of the message
to string false The receiver. The format is channel-specific
order Order true Represents an order sent from a channel
» catalogId string false The ID of the catalog the items originate from
» text string false An optional message from the customer
» items [SelectedProduct] true Products placed into the shopping cart for this order
»» productId string true The ID or SKU of the product selected
»» productName string false Name of the product
»» description string false Description of the product
»» quantity string true How many items are selected
»» itemPrice string false The price presented to the customer when choosing the product
»» currency string false The currency of the product's price
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp Whatsapp false Details specific to the WhatsApp channel
» senderName string false The 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

  • WhatsApp

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the 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 The 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

  • All

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The point in time when the event happened
userContext string false Contextual information set on the message request
whatsapp object false WhatsApp related additional information. Since 2.12
» conversation object false Conversation Information
»» conversationId string false The ID of the conversation generated by WhatsApp
»» origin string false No description
Enumerated values
Property Value
event MessageStatus::delivered
channel sms
channel whatsapp
channel viber
origin business_initiated
origin user_initiated
origin referral_conversion

Message Status: Seen

This event is triggered when the channel informs 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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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

  • All

Example payload


{
  "event": "MessageStatus::channelFailed",
  "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::channelFailed
messageId string true A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The point in time when the event happened
userContext string false Contextual information set on the message request
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

  • All

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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

  • All

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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 The channel that triggered the event. Can be empty in the case of an internal source
timestamp string(date-time) false The 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",
  "content": {
    "contentType": "text",
    "text": "A simple text message"
  }
}

Properties

*A 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 The channel that triggered the event.
receivedAt string(date-time) false The 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 The point in time when the message was received
messageId string true A message ID reference
from string true The sender of the message
to string false The receiver. The format is channel-specific
groupId string false The group ID from which the event originates. Only present if the message was sent into a group.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL 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
contentType reaction
contentType unknown
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

The 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 A plain ID of the media to download
» caption string false A caption specified by the user or the file name of the document
reaction MoReaction false An emoji reaction to a formely sent message
» messageId String false The messageId of the message this reaction is belonging to.
» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
Enumerated values
Property Value
contentType text
contentType media
contentType location
contentType contacts
contentType reaction
contentType unknown
type image
type document
type audio
type voice
type video

MoContext

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697a",
  "isForwarded": true,
  "isFrequentlyForwarded": true,
  "product": {
    "catalogId": "23343-12342",
    "productId": "123-SKU-12432",
    "metaProductId": 12345678,
    "name": "product 123",
    "description": "This is a short description for product 123",
    "price": "€49.99",
    "currency": "EUR",
    "salePrice": "€24.99",
    "inventory": 100,
    "url": "some-valid-url.com/product123",
    "imageUrl": "some-valid-url.com/product123.png"
  }
}

Properties

Contextual information of the mobile-originated message

Name Type Required Description
messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
isForwarded boolean false Is the message forwarded by the user?
isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
product Product false A product that got a question
» catalogId string false The Id of the catalog
» productId string false The ID or SKU of the product
» metaProductId string false The ID for the product on Meta's side
» name string false The name of the product
» description string false The description of the product
» price string false The price of the product
» currency string false The currency of the price
» salePrice string false The discounted price of the product
» inventory integer false The current stock for the product
» url string false The URL of the product
» imageUrl string false The image URL of the product

Product

{
  "catalogId": "23343-12342",
  "productId": "123-SKU-12432",
  "metaProductId": 12345678,
  "name": "product 123",
  "description": "This is a short description for product 123",
  "price": "€49.99",
  "currency": "EUR",
  "salePrice": "€24.99",
  "inventory": 100,
  "url": "some-valid-url.com/product123",
  "imageUrl": "some-valid-url.com/product123.png"
}

Properties

A product that got a question

Name Type Required Description
catalogId string false The Id of the catalog
productId string false The ID or SKU of the product
metaProductId string false The ID for the product on Meta's side
name string false The name of the product
description string false The description of the product
price string false The price of the product
currency string false The currency of the price
salePrice string false The discounted price of the product
inventory integer false The current stock for the product
url string false The URL of the product
imageUrl string false The image URL of the product

MoReaction

{
  "messageId": "wamid.HBgMNDkxNzk3ODEwNTM1FQIAEhgUM0E5Mjg5NUVGMEJBMzcwMENERDEB",
  "emoji": "😀"
}

Properties

An emoji reaction to a formely sent message

Name Type Required Description
messageId String false The messageId of the message this reaction is belonging to.
emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.

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 a 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 A plain ID of the media to download
caption string false A 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

*A 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 The 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 customers.
»» 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 customers.
» 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 customers.
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

*A 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 The channel that triggered the event.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp Whatsapp false Details specific to the WhatsApp channel
» senderName string false The name of the sender, set in his or her profile
Enumerated values
Property Value
channel whatsapp
contentType text
contentType media
contentType location
contentType contacts
contentType reaction
contentType unknown
type image
type document
type audio
type voice
type video

Whatsapp

{
  "senderName": "Peter"
}

Properties

Details specific to the WhatsApp channel

Name Type Required Description
senderName string false The 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

*A 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 The channel that triggered the event.
content MoContent true The 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 A plain ID of the media to download
»» caption string false A caption specified by the user or the file name of the document
» reaction MoReaction false An emoji reaction to a formely sent message
»» messageId String false The messageId of the message this reaction is belonging to.
»» emoji String false The actual reaction consisting of exactly on emoji, or an empty string indicating deletion of a reaction.
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
Enumerated values
Property Value
channel viber
contentType text
contentType media
contentType location
contentType contacts
contentType reaction
contentType unknown
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 The channel that triggered the event.
timestamp string(date-time) true The point in time when the message was received
messageId string true A message ID reference
from string false The sender of the message
to string false The receiver. The format is channel-specific
groupId string false The 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 The 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. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp WhatsAppPostBack false Postback data for a WhatsApp quick reply button
» text string false The caption of the button that was clicked
» title string false The title of the interactive item clicked
» description string false The 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",
        "productName": "product 1",
        "description": "short description",
        "quantity": 123,
        "itemPrice": 123.22,
        "currency": "EUR"
      },
      {
        "productId": "24-1111134-sdfk",
        "productName": "product 2",
        "description": "short description",
        "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 The channel that triggered the event.
timestamp string(date-time) true The point in time when the message was received
messageId string true A message ID reference
from string false The sender of the message
to string false The receiver. The format is channel-specific
order Order true Represents an order sent from a channel
» catalogId string false The ID of the catalog the items originate from
» text string false An optional message from the customer
» items [SelectedProduct] true Products placed into the shopping cart for this order
»» productId string true The ID or SKU of the product selected
»» productName string false Name of the product
»» description string false Description of the product
»» quantity string true How many items are selected
»» itemPrice string false The price presented to the customer when choosing the product
»» currency string false The currency of the product's price
context MoContext false Contextual information of the mobile-originated message
» messageId string false The message ID the MoMessage refers to. Usually set when the sender replies to a specific message
» isForwarded boolean false Is the message forwarded by the user?
» isFrequentlyForwarded boolean false Is the message frequently forwarded? The definition of frequently depends on the channel
» product Product false A product that got a question
»» catalogId string false The Id of the catalog
»» productId string false The ID or SKU of the product
»» metaProductId string false The ID for the product on Meta's side
»» name string false The name of the product
»» description string false The description of the product
»» price string false The price of the product
»» currency string false The currency of the price
»» salePrice string false The discounted price of the product
»» inventory integer false The current stock for the product
»» url string false The URL of the product
»» imageUrl string false The image URL of the product
whatsapp Whatsapp false Details specific to the WhatsApp channel
» senderName string false The 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 The 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 The caption of the button that was clicked
title string false The title of the interactive item clicked
description string false The 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",
      "productName": "product 123",
      "description": "This is a short description for product 123",
      "quantity": 1,
      "itemPrice": 0.11,
      "currency": "EUR"
    }
  ]
}

Properties

Represents an order sent from a channel

Name Type Required Description
catalogId string false The ID of the catalog the items originate from
text string false An optional message from the customer
items [SelectedProduct] true Products placed into the shopping cart for this order
» productId string true The ID or SKU of the product selected
» productName string false Name of the product
» description string false Description of the product
» quantity string true How many items are selected
» itemPrice string false The price presented to the customer when choosing the product
» currency string false The currency of the product's price

SelectedProduct

{
  "productId": "test-sku-1234",
  "productName": "product 123",
  "description": "This is a short description for product 123",
  "quantity": 1,
  "itemPrice": 0.11,
  "currency": "EUR"
}

Properties

Product selected for an order

Name Type Required Description
productId string true The ID or SKU of the product selected
productName string false Name of the product
description string false Description of the product
quantity string true How many items are selected
itemPrice string false The price presented to the customer when choosing the product
currency string false The currency of the product's price

MessageStatusDeletedEvent

{
  "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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the 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 The 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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The point in time when the event happened
userContext string false Contextual information set on the message request
whatsapp object false WhatsApp related additional information. Since 2.12
» conversation object false Conversation Information
»» conversationId string false The ID of the conversation generated by WhatsApp
»» origin string false No description
Enumerated values
Property Value
event MessageStatus::delivered
channel sms
channel whatsapp
channel viber
origin business_initiated
origin user_initiated
origin referral_conversion

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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"
}

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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The point in time when the event happened
userContext string false Contextual information set on the message request
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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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 A global message ID reference
channel string true The channel that triggered the event. Can be empty in the case of an internal source.
timestamp string(date-time) true The 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

Conversations Select API

Version: v3.0

Specification Release Notes Postman Collection Other versions

The conversations select API allows you to set channel flow selections to reach your end users by applying smart rule based flows that will try multiple channels until a successful dispatch.

Usage over underlying channels.

For each channel used on channel selection you may refer to the corresponding channel API documentation.

Examples on usage

Send a message first by trying whatsapp channel but only if the destination country is in Germany.

curl --location --request POST 'https://api.tyntec.com/conversations/select/v1/run' \
--header 'apiKey: my api key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "input": {
        "to": "49123123123",
        "text": "hello world"
    },
    "flow": {
        "name": "boom",
        "steps": [
            {
                "name": "send via WA",
                "channel": "conversations",
                "request": {
                    "from": "49123123123",
                    "to": "{{to}}",
                    "channel": "whatsapp",
                    "content": {
                        "contentType": "template",
                        "template": {
                            "templateId": "test_limit_template",
                            "templateLanguage": "en",
                            "components": {
                                "body": [
                                    {
                                        "type": "text",
                                        "text": "{{text}}"
                                    }
                                ]
                            }
                        }
                    }
                },
                "match": {
                    "countries": [
                        "DE"
                    ]
                }
            },
            {
                "name": "send via SMS",
                "channel": "sms",
                "request": {
                    "from": "tyntec",
                    "to": "{{to}}",
                    "message": "{{text}}"
                }
            }
        ]
    },
    "callback": {
        "url": "https://webhook.site/ce0b0f49-4797-4bd1-8a94-7400bb31d240"
    }
}'

As the initial request is too verbose, the flow can be first saved.

curl --location --request POST 'https://api.tyntec.com/conversations/select/v1/flows' \
--header 'apiKey: my api key' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "boom",
    "steps": [
        {
            "name": "send via WA",
            "order": 1,
            "channel": "conversations",
            "request": {
                "from": "49123123123",
                "to": "{{to}}",
                "channel": "whatsapp",
                "content": {
                    "contentType": "template",
                    "template": {
                        "templateId": "test_limit_template",
                        "templateLanguage": "en",
                        "components": {
                            "body": [
                                {
                                    "type": "text",
                                    "text": "{{text}}"
                                }
                            ]
                        }
                    }
                }
            },
            "match": {
              "countries": [
              "DE"
              ]
                }
        },
        {
            "name": "send via SMS",
            "order": 2,
            "channel": "sms",
            "request": {
                "from": "tyntec",
                "to": "{{to}}}",
                "message": "{{text}}"
            }
        }
    ]
}' 

In the response there will be a new flow with an ID created and now to initiate a flow the run request can change to this:

curl --location --request POST 'https://api.tyntec.com/conversations/select/v1/run' \
--header 'apiKey: my api key' \
--header 'Content-Type: application/json' \
--data-raw '{
  {
    "input":{
        "to":"49123123123",
        "text": "hello world"
    },
    "flowId": "a0157a44-0912-4659-92c6-7e22edc88619",
    "callback":{
        "url":"https://webhook.site/b3b14edc-ffa7-4e7d-bcb3-26360200073a"
    }
  }

Base URLs

FlowManagement

In this section operations that have to do with stored flows

Get stored flows

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/flows \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/flows HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/flows',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/flows', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/flows', 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/conversations/select/v1/flows");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/flows", data)
    req.Header = headers

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

GET /flows

Get all stored flows created under your account

Example responses

200 Response

[
  {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  }
]

400 Response

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

Responses

Status Meaning Description Schema
200 OK All stored flows on the account Inline
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [Flow] false none [The flow structure.]
» flowId string(uuid) false none The flow unique ID
» name string false none A friendly name for this flow.
» callback FlowCallbackSetting false none The flow structure.
»» url string(url) false none The callback URL to receive the events of this Flow execution.
»» headers object false none An additional custom header to be sent with the event transmission. Can be used for setting
authentication tokens, or similar.
»»» key string true none The name of the HTTP header
»»» value string true none The value of the HTTP header
» steps [FlowStep] false none Steps of this flow to execute.
»» id string(uuid) false none The flow step unique ID. Will be Autogenerated.
»» name string false none A friendly name for this flow step.
»» order integer¦null false none The order of step execution. If not set will get the list index order number.
»» channel string false none none
»» request any false none none

oneOf

Name Type Required Restrictions Description
»»» anonymous object false none none
»»»» to string true none Destination phone number in the international phone format E.164
»»»» from string true none This parameter provides identification of the sending party, which can either be a phone number in the international format or an alphanumeric identifier with up to 11 characters.

Some destination networks impose restrictions on the sender ID format. Please check the coverage list
and contact us for more information.
»»»» message string true none The message will be sent with characters encoded either in the GSM standard alphabet (GSM-7) or GSM Unicode alphabet (UCS-2).

- GSM standard alphabet GSM-7. Maximum length is 160 characters per a single message and 152 characters
per a concatenated message.
- GSM Unicode alphabet UCS-2. Maximum length is 70 characters per a single message and 66 characters
per a concatenated message.

tyntec automatically splits a sent message into concatenated messages if the message
exceeds the given limits. These concatenated messages are unified by the handset once again and
they are displayed as one message (if supported by the handset).

tyntec will charge for each part of the concatenated message as for an individual message.
»»»» encoding string false none Encoding selection between GSM7, UNICODE, or the default AUTO selection
»»»» gateway string false none Which gateway to use for the message delivery
»»»» conversion boolean false none Whether this message is subject to conversion ratio
»»»» sendDateTime string false none Any future date in the format of “yyyy-MM-ddT-HH:mm:ss+HH:mm” ISO 8601; if not set, the message will be sent immediately. The default time zone is UTC.
»»»» validity string false none Message validity in minutes
»»»» reference string false none Customer reference attached to the Delivery Reports
»»»» callbackUrl string false none Your URL for delivering the Delivery Reports; leave empty for no Delivery Report.
»»»» callbackMethod string false none Your prefered HTTP method for the Delivery Report callback; possible values are POST/GET.
»»»» partLimit integer(int32) false none Up to how many parts you allow this message can concatenated
»»»» trate number(double) false none Controls the transcoding rate of the original message to GSM-7 compatible characters; this can be used to compress the message.
»»»» mrate number(double) false none Controls the replacement rate of characters incompatible with GSM-7; they are replaced with '.'.
»»»» upperCased boolean false none Whether you allow the transcoder to try an upper case version of the content in the case this improves the produced parts of the message
»»»» keepEmojis boolean false none Whether you allow the transcoder to keep emojis
»»»» flash boolean false none Whether this SMS will be delivered as flash; some networks do not support it.

xor

Name Type Required Restrictions Description
»»» anonymous object false none The message you would like to send
»»»» to string true none The message's recipient
The format depends on the specific channel
»»»» from string true none The sender of the messages. The format depends on the specific channel.
»»»» channel string true none The channel selected for delivery.
»»»» overrides object false none Overrides of defaults for this message
»»»»» 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.
»»»» context string false none The context for this particular message
»»»» content any false none none

xor

Name Type Required Restrictions Description
»»» anonymous object false none Contract Array Response schema
»»»» from string true none Phone number of the calling party in the international format E.164
»»»» to string true none Phone number of the callee party in the international format E.164
»»»» message string true none The message you want to send via TTS call
»»»» language string true none language
»»»» initialDelay integer(int32) false none The initial pause before the TTS is announced through the call.
»»»» eventsUrl string false none Your URL for delivering the events for this call; leave empty for no events push.

continued

Name Type Required Restrictions Description
»» match MatchRule false none none
»»» id string(uuid) false none The match rule unique ID. Will be Autogenerated.
»»» enabled boolean false none Is this rule enabled or not. By default is to true.
»»» countries [string] false none none
»»» prefixes [string] false none none
»» next NexRule false none none
»»» id string(uuid) false none The next rule unique ID. Will be Autogenerated.
»»» enabled boolean false none Is this rule enabled or not. By default is to true.
»»» onFailedSubmit boolean false none If the channel didnt accept the request should it move to the next step or fail.
»»» statuses [string] false none none
Enumerated values
Property Value
channel sms
channel conversations
channel tts
encoding AUTO
encoding GDM7
encoding UNICODE
callbackMethod POST
callbackMethod GET
language ar_eg
language ar_sa
language bg_bg
language ca_es
language zh_cn
language zh_hk
language zh_tw
language hr_hr
language cs_cz
language da_dk
language nl_be
language nl_nl
language en_au
language en_ca
language en_gb
language en_in
language en_ie
language en_us
language fi_fi
language fr_ca
language fr_fr
language fr_ch
language de_at
language de_de
language de_ch
language el_gr
language he_il
language hi_in
language hu_hu
language id_id
language it_it
language ja_jp
language ko_kr
language ms_my
language nb_no
language pl_pl
language pt_pt
language ro_ro
language ru_ru
language sk_sk
language sl_si
language es_mx
language es_es
language sv_se
language ta_in
language th_th
language tr_tr
language vi_vn

Create a new flow

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/select/v1/flows \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST https://api.tyntec.com/conversations/select/v1/flows HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows',
{
  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'
}

result = RestClient.post 'https://api.tyntec.com/conversations/select/v1/flows',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/select/v1/flows', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('POST','https://api.tyntec.com/conversations/select/v1/flows', 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/conversations/select/v1/flows");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/conversations/select/v1/flows", data)
    req.Header = headers

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

POST /flows

Creates a new flow and stores it

Body parameter

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}

Parameters

Name In Type Required Description
body body Flow false none

Example responses

200 Response

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK All stored flows on the account Flow
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Get a flow

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/flows/{flowId} \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/flows/{flowId} HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/flows/{flowId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/flows/{flowId}', 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/conversations/select/v1/flows/{flowId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}", data)
    req.Header = headers

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

GET /flows/{flowId}

Get an existing flow

Parameters

Name In Type Required Description
flowId path string true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.

Example responses

200 Response

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK The stored flow for this ID Flow
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Patch a flow

Code samples

# You can also use wget
curl -X PATCH https://api.tyntec.com/conversations/select/v1/flows/{flowId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

PATCH https://api.tyntec.com/conversations/select/v1/flows/{flowId} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "name": "string",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
{
  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/json'
}

result = RestClient.patch 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.patch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('PATCH','https://api.tyntec.com/conversations/select/v1/flows/{flowId}', 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/conversations/select/v1/flows/{flowId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}", data)
    req.Header = headers

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

PATCH /flows/{flowId}

Patch an existing flow

Body parameter

{
  "name": "string",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  }
}

Parameters

Name In Type Required Description
body body PatchFlowRequest false none
flowId path string true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.

Example responses

200 Response

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK Get patched flow Flow
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Delete a flow

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/select/v1/flows/{flowId} \
  -H 'Accept: application/problem+json'

DELETE https://api.tyntec.com/conversations/select/v1/flows/{flowId} HTTP/1.1
Host: api.tyntec.com
Accept: application/problem+json


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

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
{
  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'
}

result = RestClient.delete 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/select/v1/flows/{flowId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('DELETE','https://api.tyntec.com/conversations/select/v1/flows/{flowId}', 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/conversations/select/v1/flows/{flowId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/problem+json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}", data)
    req.Header = headers

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

DELETE /flows/{flowId}

Delete an existing flow

Parameters

Name In Type Required Description
flowId path string true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.

Example responses

400 Response

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

403 Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 Flow deleted. None
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Get all steps of a flow

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps', 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/conversations/select/v1/flows/{flowId}/steps");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps", data)
    req.Header = headers

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

GET /flows/{flowId}/steps

Get all steps existing in this flow

Parameters

Name In Type Required Description
flowId path string true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.

Example responses

200 Response

[
  {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "order": 1,
    "channel": "sms",
    "request": {
      "to": "+123456789",
      "from": "tyntec",
      "message": "Hello world!"
    },
    "match": {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "enabled": true,
      "countries": [
        "string"
      ],
      "prefixes": [
        "string"
      ]
    },
    "next": {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "enabled": true,
      "onFailedSubmit": true,
      "statuses": [
        "string"
      ]
    }
  }
]

400 Response

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

Responses

Status Meaning Description Schema
200 OK The stored steps flow for this ID Inline
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [FlowStep] false none [A flow step definition.]
» id string(uuid) false none The flow step unique ID. Will be Autogenerated.
» name string false none A friendly name for this flow step.
» order integer¦null false none The order of step execution. If not set will get the list index order number.
» channel string false none none
» request any false none none

oneOf

Name Type Required Restrictions Description
»» anonymous object false none none
»»» to string true none Destination phone number in the international phone format E.164
»»» from string true none This parameter provides identification of the sending party, which can either be a phone number in the international format or an alphanumeric identifier with up to 11 characters.

Some destination networks impose restrictions on the sender ID format. Please check the coverage list
and contact us for more information.
»»» message string true none The message will be sent with characters encoded either in the GSM standard alphabet (GSM-7) or GSM Unicode alphabet (UCS-2).

- GSM standard alphabet GSM-7. Maximum length is 160 characters per a single message and 152 characters
per a concatenated message.
- GSM Unicode alphabet UCS-2. Maximum length is 70 characters per a single message and 66 characters
per a concatenated message.

tyntec automatically splits a sent message into concatenated messages if the message
exceeds the given limits. These concatenated messages are unified by the handset once again and
they are displayed as one message (if supported by the handset).

tyntec will charge for each part of the concatenated message as for an individual message.
»»» encoding string false none Encoding selection between GSM7, UNICODE, or the default AUTO selection
»»» gateway string false none Which gateway to use for the message delivery
»»» conversion boolean false none Whether this message is subject to conversion ratio
»»» sendDateTime string false none Any future date in the format of “yyyy-MM-ddT-HH:mm:ss+HH:mm” ISO 8601; if not set, the message will be sent immediately. The default time zone is UTC.
»»» validity string false none Message validity in minutes
»»» reference string false none Customer reference attached to the Delivery Reports
»»» callbackUrl string false none Your URL for delivering the Delivery Reports; leave empty for no Delivery Report.
»»» callbackMethod string false none Your prefered HTTP method for the Delivery Report callback; possible values are POST/GET.
»»» partLimit integer(int32) false none Up to how many parts you allow this message can concatenated
»»» trate number(double) false none Controls the transcoding rate of the original message to GSM-7 compatible characters; this can be used to compress the message.
»»» mrate number(double) false none Controls the replacement rate of characters incompatible with GSM-7; they are replaced with '.'.
»»» upperCased boolean false none Whether you allow the transcoder to try an upper case version of the content in the case this improves the produced parts of the message
»»» keepEmojis boolean false none Whether you allow the transcoder to keep emojis
»»» flash boolean false none Whether this SMS will be delivered as flash; some networks do not support it.

xor

Name Type Required Restrictions Description
»» anonymous object false none The message you would like to send
»»» to string true none The message's recipient
The format depends on the specific channel
»»» from string true none The sender of the messages. The format depends on the specific channel.
»»» channel string true none The channel selected for delivery.
»»» overrides object false none Overrides of defaults for this message
»»»» 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.
»»» context string false none The context for this particular message
»»» content any false none none

xor

Name Type Required Restrictions Description
»» anonymous object false none Contract Array Response schema
»»» from string true none Phone number of the calling party in the international format E.164
»»» to string true none Phone number of the callee party in the international format E.164
»»» message string true none The message you want to send via TTS call
»»» language string true none language
»»» initialDelay integer(int32) false none The initial pause before the TTS is announced through the call.
»»» eventsUrl string false none Your URL for delivering the events for this call; leave empty for no events push.

continued

Name Type Required Restrictions Description
» match MatchRule false none none
»» id string(uuid) false none The match rule unique ID. Will be Autogenerated.
»» enabled boolean false none Is this rule enabled or not. By default is to true.
»» countries [string] false none none
»» prefixes [string] false none none
» next NexRule false none none
»» id string(uuid) false none The next rule unique ID. Will be Autogenerated.
»» enabled boolean false none Is this rule enabled or not. By default is to true.
»» onFailedSubmit boolean false none If the channel didnt accept the request should it move to the next step or fail.
»» statuses [string] false none none
Enumerated values
Property Value
channel sms
channel conversations
channel tts
encoding AUTO
encoding GDM7
encoding UNICODE
callbackMethod POST
callbackMethod GET
language ar_eg
language ar_sa
language bg_bg
language ca_es
language zh_cn
language zh_hk
language zh_tw
language hr_hr
language cs_cz
language da_dk
language nl_be
language nl_nl
language en_au
language en_ca
language en_gb
language en_in
language en_ie
language en_us
language fi_fi
language fr_ca
language fr_fr
language fr_ch
language de_at
language de_de
language de_ch
language el_gr
language he_il
language hi_in
language hu_hu
language id_id
language it_it
language ja_jp
language ko_kr
language ms_my
language nb_no
language pl_pl
language pt_pt
language ro_ro
language ru_ru
language sk_sk
language sl_si
language es_mx
language es_es
language sv_se
language ta_in
language th_th
language tr_tr
language vi_vn

Adds a new step on the flow

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps',
{
  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'
}

result = RestClient.post 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('POST','https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps', 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/conversations/select/v1/flows/{flowId}/steps");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps", data)
    req.Header = headers

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

POST /flows/{flowId}/steps

Adds a new step on the flow. CAUTION this will have immediate impact to all new requests using this flow.

Body parameter

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

Parameters

Name In Type Required Description
body body FlowStep false none
flowId path string true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.

Example responses

200 Response

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK The newly created step. FlowStep
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Get step of a flow

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', 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/conversations/select/v1/flows/{flowId}/steps/{stepId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}", data)
    req.Header = headers

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

GET /flows/{flowId}/steps/{stepId}

Get step of the flow.

Parameters

Name In Type Required Description
flowId path string(uuid) true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.
stepId path string(uuid) true The stepId of the step flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}/steps/{stepId}.

Example responses

200 Response

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK Get step with ID from this flow. FlowStep
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Delete flow step

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} \
  -H 'Accept: application/problem+json'

DELETE https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.tyntec.com
Accept: application/problem+json


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

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
{
  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'
}

result = RestClient.delete 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('DELETE','https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', 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/conversations/select/v1/flows/{flowId}/steps/{stepId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/problem+json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}", data)
    req.Header = headers

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

DELETE /flows/{flowId}/steps/{stepId}

Deletes a flow step.

Parameters

Name In Type Required Description
flowId path string(uuid) true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.
stepId path string(uuid) true The stepId of the step flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}/steps/{stepId}.

Example responses

400 Response

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

403 Response

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 Flow step deleted. None
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Patch a flow step

Code samples

# You can also use wget
curl -X PATCH https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

PATCH https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId} HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
{
  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/json'
}

result = RestClient.patch 'https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.patch('https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('PATCH','https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}', 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/conversations/select/v1/flows/{flowId}/steps/{stepId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("PATCH");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("PATCH", "https://api.tyntec.com/conversations/select/v1/flows/{flowId}/steps/{stepId}", data)
    req.Header = headers

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

PATCH /flows/{flowId}/steps/{stepId}

Patches a flow step.

Body parameter

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

Parameters

Name In Type Required Description
body body FlowStep false none
flowId path string(uuid) true The flowId of the flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}.
stepId path string(uuid) true The stepId of the step flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/{flowId}/steps/{stepId}.

Example responses

200 Response

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK Returns the changed step. FlowStep
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

FlowControl

In this section operations that have to do with flow execution are described

Initiate a flow

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/select/v1/run \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST https://api.tyntec.com/conversations/select/v1/run HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "disableNotMatchingSteps": true,
  "returnCompiledFlow": true,
  "reference": "string",
  "input": {
    "key": "string",
    "value": "stringst"
  }
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/run',
{
  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'
}

result = RestClient.post 'https://api.tyntec.com/conversations/select/v1/run',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/select/v1/run', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('POST','https://api.tyntec.com/conversations/select/v1/run', 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/conversations/select/v1/run");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/conversations/select/v1/run", data)
    req.Header = headers

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

POST /run

Starts a flow. Either an existing flowId needs to be provided or a flow definition must be present.

Body parameter

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "disableNotMatchingSteps": true,
  "returnCompiledFlow": true,
  "reference": "string",
  "input": {
    "key": "string",
    "value": "stringst"
  }
}

Parameters

Name In Type Required Description
body body any false none

Example responses

202 Response

{
  "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "FlowStatus": "accepted",
  "timestamp": "2019-08-24T14:15:22Z",
  "currentStepId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "compiledFlow": {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  },
  "stepStates": {
    "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
    "value": "skipped"
  }
}

400 Response

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

Responses

Status Meaning Description Schema
202 Accepted Returns the changed step. FlowInstance
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Get a running flow status

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId} \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId} HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}', 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/conversations/select/v1/running/{flowInstanceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}", data)
    req.Header = headers

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

GET /running/{flowInstanceId}

Returns a running flow.

Parameters

Name In Type Required Description
flowInstanceId path string(uuid) true The flowInstanceId of the running flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/running/{flowInstanceId}.

Example responses

200 Response

{
  "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "FlowStatus": "accepted",
  "timestamp": "2019-08-24T14:15:22Z",
  "currentStepId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "compiledFlow": {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  },
  "stepStates": {
    "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
    "value": "skipped"
  }
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK Returns ruinning flow instance. FlowInstance
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Stops a running flow

Code samples

# You can also use wget
curl -X DELETE https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId} \
  -H 'Accept: application/json'

DELETE https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId} HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}',
{
  method: 'DELETE',

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

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json'
}

result = RestClient.delete 'https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.delete('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('DELETE','https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}', 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/conversations/select/v1/running/{flowInstanceId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("DELETE");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}", data)
    req.Header = headers

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

DELETE /running/{flowInstanceId}

Returns the stopped flow.

Parameters

Name In Type Required Description
flowInstanceId path string(uuid) true The flowInstanceId of the running flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/running/{flowInstanceId}.

Example responses

200 Response

{
  "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "FlowStatus": "accepted",
  "timestamp": "2019-08-24T14:15:22Z",
  "currentStepId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "compiledFlow": {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  },
  "stepStates": {
    "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
    "value": "skipped"
  }
}

400 Response

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

Responses

Status Meaning Description Schema
200 OK Returns ruinning flow instance. FlowInstance
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem

Get running flow recorded events.

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events', 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/conversations/select/v1/running/{flowInstanceId}/events");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/select/v1/running/{flowInstanceId}/events", data)
    req.Header = headers

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

GET /running/{flowInstanceId}/events

Returns all events recorded for this executed flow.

Parameters

Name In Type Required Description
flowInstanceId path string(uuid) true The flowInstanceId of the running flow you would like to edit. This parameter is part of the URI following the pattern ${baseURL}/flows/running/{flowInstanceId}.

Example responses

200 Response

[
  {
    "eventId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "customerId": "string",
    "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "stepInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "accountId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "reference": "string",
    "status": "skipped",
    "channel": "sms",
    "type": "flow",
    "timestamp": "2019-08-24T14:15:22Z",
    "event": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "flowInstanceId": "a9df5f5a-bcd1-4362-a6d5-466588dd8ec7",
      "status": "skipped",
      "channel": "sms",
      "requestResponseCode": 200,
      "requestResponse": {
        "doneDate": "string",
        "errorCode": "string",
        "errorReason": "string",
        "from": "+49123456789",
        "href": "string",
        "mccmnc": "string",
        "parts": [
          {
            "currency": "EUR",
            "deliveryState": "string",
            "doneDate": "string",
            "errorCode": "string",
            "partId": "string",
            "price": "0.005",
            "priceEffective": "2018-06-01T00:00:00+0200",
            "statusText": "string"
          }
        ],
        "overallPrice": "0.01",
        "priceEffective": "2019-08-24T14:15:22Z",
        "reference": "string",
        "requestId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
        "size": 1,
        "status": "DELIVERED",
        "submitDate": "2019-08-24T14:15:22Z",
        "to": "+1987654321",
        "ttid": 77292
      }
    }
  }
]

400 Response

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

Responses

Status Meaning Description Schema
200 OK Returns ruinning flow instance. Inline
400 Bad Request The request does not match our expectations. Please check the Problems object for details Problem
403 Forbidden The default response in case of any other error. Please check the error object for details Problem
404 Not Found The default response in case of any other error. Please check the error object for details Problem
default Default The default response in case of any other error. Please check the error object for details Problem
Response Schema

Status Code 200

Name Type Required Restrictions Description
anonymous [FlowEvent] false none [The flow event structure.]
» eventId string(uuid) false none The event id.
» customerId string false none The unique customer Id.
» flowInstanceId string(uuid) false none The flow unique ID
» stepInstanceId string(uuid) false none The flow step instance unique ID
» accountId string(uuid) false none The unique account ID
» reference string false none Reference value to be used on callback events.
» status string false none The flow step statuses.
» channel string false none none
» type string false none The event types.
» timestamp string(date-time) false none Point in time when the event was created.
» event any false none none

oneOf

Name Type Required Restrictions Description
»» anonymous FlowStepResponse false none The response of the underlying channel when step executed.
»»» id string(uuid) false none The unique ID.
»»» flowInstanceId string(uuid) false none The flow unique ID
»»» status string false none The flow step statuses.
»»» channel string false none none
»»» requestResponseCode integer false none The response code of the underlying channel.
»»» requestResponse object false none The response of the channel API as described in their own API Reference.

oneOf

Name Type Required Restrictions Description
»»»» anonymous FlowEvent/properties/event/oneOf/1 false none none
»»»»» doneDate string false none The time stamp when the message was successfully delivered
»»»»» errorCode string false none The error code. GSM error codes
»»»»» errorReason string false none The reason for an unsuccessful attempt.
»»»»» from string false none The phone number of the sending party in the international format if available
»»»»» href string false none The URL of the accepted message
»»»»» mccmnc string false none Representative IMSI prefix of the target network; the respective mapping can be found on http://mcc-mnc.com/.
»»»»» parts [object] false none none
»»»»»» currency string false none The currency in which the pricing is given; it corresponds to the currency of the invoice.
»»»»»» deliveryState string false none The delivery status of this specific part; possible values can be found here
»»»»»» doneDate string false none The time stamp when the message was successfully delivered
»»»»»» errorCode string false none The reason for an unsuccessful delivery attempt. GSM error codes
»»»»»» partId string false none The identification number of the specific message part
»»»»»» price string false none The price per message from the respective network; negative prices represent payouts in favor of a tyntec’s customer.
»»»»»» priceEffective string(date-time) false none The date when the “price” became effective
»»»»»» statusText string false none The first 20 characters of the sent message
»»»»» overallPrice string(string) false none The overall sum of prices for all parts of this message
»»»»» priceEffective string(date-time) false none The date when the “price” became active
»»»»» reference string false none Custom reference that will mark the Delivery Report
»»»»» requestId string false none The unique identifier provided for each messaging request
»»»»» size integer(int32) false none The amount of respective concatenated SMS parts
»»»»» status string false none The message status; the values can be found can be found here
»»»»» submitDate string(date-time) false none The date when the message was sent out by tyntec for delivery
»»»»» to string false none Your number provided by tyntec that has received the respective message in international format
»»»»» ttid string false none The tyntec operator's ID

xor

Name Type Required Restrictions Description
»»»» anonymous object false none none
»»»»» 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

xor

Name Type Required Restrictions Description
»»»» anonymous object false none Contract Entity schema
»»»»» callId string(uuid) false none Company's postal address
»»»»» status string false none Status of the call
»»»»» from string false none Phone number of the calling party in the international format E.164
»»»»» to string false none Phone number of the callee party in the international format E.164

xor

Name Type Required Restrictions Description
»» anonymous FlowEvent/properties/event/oneOf/1 false none none

xor

Name Type Required Restrictions Description
»» anonymous object false none Abstract event object produced by the API, such as MessageStatus or InboundMessage
»»» event string true none Determines the event types emitted by the API
»»» channel string true none The channel that triggered the event. Always set.
»»» timestamp string(date-time) true none The point in time when the event happened
»»» from string false none Who triggered this event. Usually a phone number or WhatsApp account ID
»»» to string false none The receiver of the event.

xor

Name Type Required Restrictions Description
»» anonymous object false none This is the event object containing informations regarding the call.
»»» callId string(uuid) false none Company's postal address
»»» direction string false none The direction of the call
»»» from string false none Phone number of the calling party in the international format E.164
»»» to string false none Phone number of the callee party in the international format E.164
»»» startTime string(date-time) false none The timestamp when the call started.
»»» answerTime string(date-time) false none The timestamp when the call was answered.
»»» endTime string(date-time) false none The timestamp when the call completed.
»»» duration string false none The duration in seconds of the call.
»»» country string false none The alpha 2 code of the destionation country.
»»» rate string false none The rate charge per minute for this country.
»»» price string false none The price charged for this call.
»»» currency string false none The currency used for this charge.
»»» network string false none The name of the network for the destination call.
»»» status string false none The status reported for this event.
Enumerated values
Property Value
status skipped
status inprogress
status next
status waiting
status comleted
status failed
channel sms
channel conversations
channel tts
type flow
type channel
type channel_response
status skipped
status inprogress
status next
status waiting
status comleted
status failed
channel sms
channel conversations
channel tts
status starting
event InboundMessage
event InboundMessage::Postback
event MessageStatus::accepted
event MessageStatus::channelFailed
event MessageStatus::deleted
event MessageStatus::delivered
event MessageStatus::failed
event MessageStatus::seen
event MessageStatus::unknown
event ChannelUpdate
channel sms
channel whatsapp
channel tyntecEcho
channel viber
direction outbound
direction inbound
status started
status early
status hangup
status ringing
status completed

Schemas

FlowRequestWithFlowId

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "disableNotMatchingSteps": true,
  "returnCompiledFlow": true,
  "reference": "string",
  "input": {
    "key": "string",
    "value": "stringst"
  }
}

The flow request with flow ID structure.

Properties

Name Type Required Restrictions Description
flowId string(uuid) true none The flow unique ID
callback FlowCallbackSetting false none Callback specific settings for this flow.
disableNotMatchingSteps boolean false none Should non matching step be disabled. Default value is true.
returnCompiledFlow boolean false none Should return in the response the compiled flow. Default value is true.
reference string false none Reference value to be used on callback events.
input object false none The key value of template parameters to be replaces in the flow definition.
» key string true none The name of the template variable.
» value string true none The value of the template variable.

FlowRequestWithFlowDefition

{
  "flow": {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  },
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "disableNotMatchingSteps": true,
  "returnCompiledFlow": true,
  "reference": "string",
  "input": {
    "key": "string",
    "value": "stringst"
  }
}

The flow request with flow ID structure.

Properties

Name Type Required Restrictions Description
flow Flow true none The flow definition.
callback FlowCallbackSetting false none Callback specific settings for this flow.
disableNotMatchingSteps boolean false none Should non matching step be disabled. Default value is true.
returnCompiledFlow boolean false none Should return in the response the compiled flow. Default value is true.
reference string false none Reference value to be used on callback events.
input object false none The key value of template parameters to be replaces in the flow definition.
» key string true none The name of the template variable.
» value string true none The value of the template variable.

FlowInstance

{
  "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "FlowStatus": "accepted",
  "timestamp": "2019-08-24T14:15:22Z",
  "currentStepId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "compiledFlow": {
    "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "name": "Flow for my product",
    "callback": {
      "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
      "headers": {
        "key": "string",
        "value": "stringst"
      }
    },
    "steps": [
      {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "name": "Flow for my product",
        "order": 1,
        "channel": "sms",
        "request": {
          "to": "+123456789",
          "from": "tyntec",
          "message": "Hello world!"
        },
        "match": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "countries": [
            "string"
          ],
          "prefixes": [
            "string"
          ]
        },
        "next": {
          "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
          "enabled": true,
          "onFailedSubmit": true,
          "statuses": [
            "string"
          ]
        }
      }
    ]
  },
  "stepStates": {
    "key": "4adfe27e-63d3-45b9-8238-62b6ed6fdb5e",
    "value": "skipped"
  }
}

The flow structure.

Properties

Name Type Required Restrictions Description
flowInstanceId string(uuid) false none The flow unique ID
FlowStatus string false none none
timestamp string(date-time) false none Point in time when the flow instance was created.
currentStepId string(uuid) false none Step id that is executed currently.
compiledFlow Flow false none The compiled flow definition.
stepStates object false none The map with the step id UUID as key and the step state as value.
» key string(uuid) true none The uuid of the step.
» value string true none The flow step statuses.
Enumerated values
Property Value
FlowStatus accepted
FlowStatus inprogress
FlowStatus completed
FlowStatus failed
FlowStatus stopped
value skipped
value inprogress
value next
value waiting
value comleted
value failed

PatchFlowRequest

{
  "name": "string",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  }
}

The flow structure.

Properties

Name Type Required Restrictions Description
name string false none The flow name to change
callback FlowCallbackSetting false none Callback specific settings for this flow.

FlowEvent

{
  "eventId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "customerId": "string",
  "flowInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "stepInstanceId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "accountId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "reference": "string",
  "status": "skipped",
  "channel": "sms",
  "type": "flow",
  "timestamp": "2019-08-24T14:15:22Z",
  "event": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "flowInstanceId": "a9df5f5a-bcd1-4362-a6d5-466588dd8ec7",
    "status": "skipped",
    "channel": "sms",
    "requestResponseCode": 200,
    "requestResponse": {
      "doneDate": "string",
      "errorCode": "string",
      "errorReason": "string",
      "from": "+49123456789",
      "href": "string",
      "mccmnc": "string",
      "parts": [
        {
          "currency": "EUR",
          "deliveryState": "string",
          "doneDate": "string",
          "errorCode": "string",
          "partId": "string",
          "price": "0.005",
          "priceEffective": "2018-06-01T00:00:00+0200",
          "statusText": "string"
        }
      ],
      "overallPrice": "0.01",
      "priceEffective": "2019-08-24T14:15:22Z",
      "reference": "string",
      "requestId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
      "size": 1,
      "status": "DELIVERED",
      "submitDate": "2019-08-24T14:15:22Z",
      "to": "+1987654321",
      "ttid": 77292
    }
  }
}

The flow event structure.

Properties

Name Type Required Restrictions Description
eventId string(uuid) false none The event id.
customerId string false none The unique customer Id.
flowInstanceId string(uuid) false none The flow unique ID
stepInstanceId string(uuid) false none The flow step instance unique ID
accountId string(uuid) false none The unique account ID
reference string false none Reference value to be used on callback events.
status string false none The flow step statuses.
channel string false none none
type string false none The event types.
timestamp string(date-time) false none Point in time when the event was created.
event any false none none

oneOf

Name Type Required Restrictions Description
» anonymous FlowStepResponse false none The response of the underlying channel when step executed.

xor

Name Type Required Restrictions Description
» anonymous object false none none
»» doneDate string false none The time stamp when the message was successfully delivered
»» errorCode string false none The error code. GSM error codes
»» errorReason string false none The reason for an unsuccessful attempt.
»» from string false none The phone number of the sending party in the international format if available
»» href string false none The URL of the accepted message
»» mccmnc string false none Representative IMSI prefix of the target network; the respective mapping can be found on http://mcc-mnc.com/.
»» parts [object] false none none
»»» currency string false none The currency in which the pricing is given; it corresponds to the currency of the invoice.
»»» deliveryState string false none The delivery status of this specific part; possible values can be found here
»»» doneDate string false none The time stamp when the message was successfully delivered
»»» errorCode string false none The reason for an unsuccessful delivery attempt. GSM error codes
»»» partId string false none The identification number of the specific message part
»»» price string false none The price per message from the respective network; negative prices represent payouts in favor of a tyntec’s customer.
»»» priceEffective string(date-time) false none The date when the “price” became effective
»»» statusText string false none The first 20 characters of the sent message
»» overallPrice string(string) false none The overall sum of prices for all parts of this message
»» priceEffective string(date-time) false none The date when the “price” became active
»» reference string false none Custom reference that will mark the Delivery Report
»» requestId string false none The unique identifier provided for each messaging request
»» size integer(int32) false none The amount of respective concatenated SMS parts
»» status string false none The message status; the values can be found can be found here
»» submitDate string(date-time) false none The date when the message was sent out by tyntec for delivery
»» to string false none Your number provided by tyntec that has received the respective message in international format
»» ttid string false none The tyntec operator's ID

xor

Name Type Required Restrictions Description
» anonymous object false none Abstract event object produced by the API, such as MessageStatus or InboundMessage
»» event string true none Determines the event types emitted by the API
»» channel string true none The channel that triggered the event. Always set.
»» timestamp string(date-time) true none The point in time when the event happened
»» from string false none Who triggered this event. Usually a phone number or WhatsApp account ID
»» to string false none The receiver of the event.

xor

Name Type Required Restrictions Description
» anonymous object false none This is the event object containing informations regarding the call.
»» callId string(uuid) false none Company's postal address
»» direction string false none The direction of the call
»» from string false none Phone number of the calling party in the international format E.164
»» to string false none Phone number of the callee party in the international format E.164
»» startTime string(date-time) false none The timestamp when the call started.
»» answerTime string(date-time) false none The timestamp when the call was answered.
»» endTime string(date-time) false none The timestamp when the call completed.
»» duration string false none The duration in seconds of the call.
»» country string false none The alpha 2 code of the destionation country.
»» rate string false none The rate charge per minute for this country.
»» price string false none The price charged for this call.
»» currency string false none The currency used for this charge.
»» network string false none The name of the network for the destination call.
»» status string false none The status reported for this event.
Enumerated values
Property Value
status skipped
status inprogress
status next
status waiting
status comleted
status failed
channel sms
channel conversations
channel tts
type flow
type channel
type channel_response
event InboundMessage
event InboundMessage::Postback
event MessageStatus::accepted
event MessageStatus::channelFailed
event MessageStatus::deleted
event MessageStatus::delivered
event MessageStatus::failed
event MessageStatus::seen
event MessageStatus::unknown
event ChannelUpdate
channel sms
channel whatsapp
channel tyntecEcho
channel viber
direction outbound
direction inbound
status started
status early
status hangup
status ringing
status completed

FlowStepResponse

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "flowInstanceId": "a9df5f5a-bcd1-4362-a6d5-466588dd8ec7",
  "status": "skipped",
  "channel": "sms",
  "requestResponseCode": 200,
  "requestResponse": {
    "doneDate": "string",
    "errorCode": "string",
    "errorReason": "string",
    "from": "+49123456789",
    "href": "string",
    "mccmnc": "string",
    "parts": [
      {
        "currency": "EUR",
        "deliveryState": "string",
        "doneDate": "string",
        "errorCode": "string",
        "partId": "string",
        "price": "0.005",
        "priceEffective": "2018-06-01T00:00:00+0200",
        "statusText": "string"
      }
    ],
    "overallPrice": "0.01",
    "priceEffective": "2019-08-24T14:15:22Z",
    "reference": "string",
    "requestId": "e74db8d4-77ad-4671-8feb-9bc76b0df188",
    "size": 1,
    "status": "DELIVERED",
    "submitDate": "2019-08-24T14:15:22Z",
    "to": "+1987654321",
    "ttid": 77292
  }
}

The response of the underlying channel when step executed.

Properties

Name Type Required Restrictions Description
id string(uuid) false none The unique ID.
flowInstanceId string(uuid) false none The flow unique ID
status string false none The flow step statuses.
channel string false none none
requestResponseCode integer false none The response code of the underlying channel.
requestResponse object false none The response of the channel API as described in their own API Reference.

oneOf

Name Type Required Restrictions Description
» anonymous FlowEvent/properties/event/oneOf/1 false none none

xor

Name Type Required Restrictions Description
» anonymous object false none none
»» 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

xor

Name Type Required Restrictions Description
» anonymous object false none Contract Entity schema
»» callId string(uuid) false none Company's postal address
»» status string false none Status of the call
»» from string false none Phone number of the calling party in the international format E.164
»» to string false none Phone number of the callee party in the international format E.164
Enumerated values
Property Value
status skipped
status inprogress
status next
status waiting
status comleted
status failed
channel sms
channel conversations
channel tts
status starting

Flow

{
  "flowId": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "callback": {
    "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
    "headers": {
      "key": "string",
      "value": "stringst"
    }
  },
  "steps": [
    {
      "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
      "name": "Flow for my product",
      "order": 1,
      "channel": "sms",
      "request": {
        "to": "+123456789",
        "from": "tyntec",
        "message": "Hello world!"
      },
      "match": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "countries": [
          "string"
        ],
        "prefixes": [
          "string"
        ]
      },
      "next": {
        "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
        "enabled": true,
        "onFailedSubmit": true,
        "statuses": [
          "string"
        ]
      }
    }
  ]
}

The flow structure.

Properties

Name Type Required Restrictions Description
flowId string(uuid) false none The flow unique ID
name string false none A friendly name for this flow.
callback FlowCallbackSetting false none Callback specific settings for this flow.
steps [FlowStep] false none Steps of this flow to execute.

FlowCallbackSetting

{
  "url": "https://webhook.site/53bd902b-fe75-40fc-b1c6-47485a3fcebe",
  "headers": {
    "key": "string",
    "value": "stringst"
  }
}

The flow structure.

Properties

Name Type Required Restrictions Description
url string(url) false none The callback URL to receive the events of this Flow execution.
headers object false none An additional custom header to be sent with the event transmission. Can be used for setting
authentication tokens, or similar.
» key string true none The name of the HTTP header
» value string true none The value of the HTTP header

FlowStep

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "name": "Flow for my product",
  "order": 1,
  "channel": "sms",
  "request": {
    "to": "+123456789",
    "from": "tyntec",
    "message": "Hello world!"
  },
  "match": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "countries": [
      "string"
    ],
    "prefixes": [
      "string"
    ]
  },
  "next": {
    "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
    "enabled": true,
    "onFailedSubmit": true,
    "statuses": [
      "string"
    ]
  }
}

A flow step definition.

Properties

Name Type Required Restrictions Description
id string(uuid) false none The flow step unique ID. Will be Autogenerated.
name string false none A friendly name for this flow step.
order integer¦null false none The order of step execution. If not set will get the list index order number.
channel string false none none
request any false none none

oneOf

Name Type Required Restrictions Description
» anonymous object false none none
»» to string true none Destination phone number in the international phone format E.164
»» from string true none This parameter provides identification of the sending party, which can either be a phone number in the international format or an alphanumeric identifier with up to 11 characters.

Some destination networks impose restrictions on the sender ID format. Please check the coverage list
and contact us for more information.
»» message string true none The message will be sent with characters encoded either in the GSM standard alphabet (GSM-7) or GSM Unicode alphabet (UCS-2).

- GSM standard alphabet GSM-7. Maximum length is 160 characters per a single message and 152 characters
per a concatenated message.
- GSM Unicode alphabet UCS-2. Maximum length is 70 characters per a single message and 66 characters
per a concatenated message.

tyntec automatically splits a sent message into concatenated messages if the message
exceeds the given limits. These concatenated messages are unified by the handset once again and
they are displayed as one message (if supported by the handset).

tyntec will charge for each part of the concatenated message as for an individual message.
»» encoding string false none Encoding selection between GSM7, UNICODE, or the default AUTO selection
»» gateway string false none Which gateway to use for the message delivery
»» conversion boolean false none Whether this message is subject to conversion ratio
»» sendDateTime string false none Any future date in the format of “yyyy-MM-ddT-HH:mm:ss+HH:mm” ISO 8601; if not set, the message will be sent immediately. The default time zone is UTC.
»» validity string false none Message validity in minutes
»» reference string false none Customer reference attached to the Delivery Reports
»» callbackUrl string false none Your URL for delivering the Delivery Reports; leave empty for no Delivery Report.
»» callbackMethod string false none Your prefered HTTP method for the Delivery Report callback; possible values are POST/GET.
»» partLimit integer(int32) false none Up to how many parts you allow this message can concatenated
»» trate number(double) false none Controls the transcoding rate of the original message to GSM-7 compatible characters; this can be used to compress the message.
»» mrate number(double) false none Controls the replacement rate of characters incompatible with GSM-7; they are replaced with '.'.
»» upperCased boolean false none Whether you allow the transcoder to try an upper case version of the content in the case this improves the produced parts of the message
»» keepEmojis boolean false none Whether you allow the transcoder to keep emojis
»» flash boolean false none Whether this SMS will be delivered as flash; some networks do not support it.

xor

Name Type Required Restrictions Description
» anonymous object false none The message you would like to send
»» to string true none The message's recipient
The format depends on the specific channel
»» from string true none The sender of the messages. The format depends on the specific channel.
»» channel string true none The channel selected for delivery.
»» overrides object false none Overrides of defaults for this message
»»» 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.
»» context string false none The context for this particular message
»» content any false none none

xor

Name Type Required Restrictions Description
» anonymous object false none Contract Array Response schema
»» from string true none Phone number of the calling party in the international format E.164
»» to string true none Phone number of the callee party in the international format E.164
»» message string true none The message you want to send via TTS call
»» language string true none language
»» initialDelay integer(int32) false none The initial pause before the TTS is announced through the call.
»» eventsUrl string false none Your URL for delivering the events for this call; leave empty for no events push.

continued

Name Type Required Restrictions Description
match MatchRule false none Matching rule for this step.
next NexRule false none Rule to move to the next step.
Enumerated values
Property Value
channel sms
channel conversations
channel tts
encoding AUTO
encoding GDM7
encoding UNICODE
callbackMethod POST
callbackMethod GET
language ar_eg
language ar_sa
language bg_bg
language ca_es
language zh_cn
language zh_hk
language zh_tw
language hr_hr
language cs_cz
language da_dk
language nl_be
language nl_nl
language en_au
language en_ca
language en_gb
language en_in
language en_ie
language en_us
language fi_fi
language fr_ca
language fr_fr
language fr_ch
language de_at
language de_de
language de_ch
language el_gr
language he_il
language hi_in
language hu_hu
language id_id
language it_it
language ja_jp
language ko_kr
language ms_my
language nb_no
language pl_pl
language pt_pt
language ro_ro
language ru_ru
language sk_sk
language sl_si
language es_mx
language es_es
language sv_se
language ta_in
language th_th
language tr_tr
language vi_vn

MatchRule

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "enabled": true,
  "countries": [
    "string"
  ],
  "prefixes": [
    "string"
  ]
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none The match rule unique ID. Will be Autogenerated.
enabled boolean false none Is this rule enabled or not. By default is to true.
countries [string] false none none
prefixes [string] false none none

NexRule

{
  "id": "6499570c-58db-487d-9afa-a1d9f98959fe",
  "enabled": true,
  "onFailedSubmit": true,
  "statuses": [
    "string"
  ]
}

Properties

Name Type Required Restrictions Description
id string(uuid) false none The next rule unique ID. Will be Autogenerated.
enabled boolean false none Is this rule enabled or not. By default is to true.
onFailedSubmit boolean false none If the channel didnt accept the request should it move to the next step or fail.
statuses [string] false none none

Problem

{
  "type": "https://docs.tyntec.com/problems/DataNotParseable",
  "title": "Data given was not parseable",
  "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 false none A URI reference [RFC3986] that identifies the problem type
title string false none A short, human-readable summary of the problem type.
status number false none The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
detail string false none A human-readable explanation specific to this occurrence of the problem.

Partner API

Version: v1 (beta)

Specification Release Notes Other versions

The embedded sign up API allows you to manage requests for embedded sign ups with WhatsApp.

Note: The embedded sign up request API for WhatsApp is only available to registered partners. Refer to our documentation for further details.

Base URLs

Manage new requests

This section covers the basic interactions for submitting a new embedded sign up request and getting information about it

Create a new signup request

Code samples

# You can also use wget
curl -X POST https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups HTTP/1.1
Host: api.tyntec.com
Content-Type: application/json
Accept: application/json

const inputBody = '{
  "profile": {
    "displayName": "string",
    "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.",
    "logoUrl": "string"
  },
  "pricing": {
    "selectedPlanId": 0
  },
  "companyDetails": {
    "companyName": "string",
    "companyAddress": "string",
    "postalCode": "string",
    "city": "string",
    "country": "string"
  },
  "webhookSpecification": {
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    }
  },
  "successRedirectUrl": "string",
  "failureRedirectUrl": "string",
  "statusCallbackMetaData": "string",
  "statusCallbackUrl": "string"
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups',
{
  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'
}

result = RestClient.post 'https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.post('https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('POST','https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups', 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/conversations/v3/channels/whatsapp/isv-sign-ups");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
con.setRequestProperty("Content-Type", "application/json");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "https://api.tyntec.com/conversations/v3/channels/whatsapp/isv-sign-ups", data)
    req.Header = headers

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

POST /channels/whatsapp/isv-sign-ups

Create a new signup request

Body parameter

{
  "profile": {
    "displayName": "string",
    "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.",
    "logoUrl": "string"
  },
  "pricing": {
    "selectedPlanId": 0
  },
  "companyDetails": {
    "companyName": "string",
    "companyAddress": "string",
    "postalCode": "string",
    "city": "string",
    "country": "string"
  },
  "webhookSpecification": {
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    }
  },
  "successRedirectUrl": "string",
  "failureRedirectUrl": "string",
  "statusCallbackMetaData": "string",
  "statusCallbackUrl": "string"
}

Parameters

Name In Type Required Description
body body ISVEmbeddedSignupRequest true The data required to submit a new request

Example responses

202 Response

{
  "requestId": "string",
  "redirectUrl": "string"
}

Responses

Status Meaning Description Schema
202 Accepted Response after the server has accepted the request ISVEmbeddedSignupRequestResponse

Returns a signup request

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId} \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId} HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId}',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId}',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId}', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId}', 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/conversations/v3/channels/whatsapp/sign-ups/{requestId}");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/{requestId}", data)
    req.Header = headers

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

GET /channels/whatsapp/sign-ups/{requestId}

Returns a signup request

Parameters

Name In Type Required Description
request-id path string(uuid) true The request id returned by our platform

Example responses

200 Response

{
  "requestId": "string",
  "countryCode": 0,
  "phoneNumber": "string",
  "profile": {
    "displayName": "string",
    "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.",
    "logoUrl": "string"
  },
  "companyDetails": {
    "companyName": "string",
    "companyAddress": "string",
    "postalCode": "string",
    "city": "string",
    "country": "string"
  },
  "pricing": {
    "selectedPlanId": 0
  },
  "status": "pending",
  "failureReason": "string",
  "whatsAppAccountId": "string",
  "apiAccountName": "string",
  "successRedirectUrl": "string",
  "failureRedirectUrl": "string",
  "statusCallbackMetaData": "string",
  "statusCallbackUrl": "string",
  "createdAt": "2020-02-15T23:28:34.442Z",
  "lastUpdated": "2020-02-15T23:28:34.442Z"
}

Responses

Status Meaning Description Schema
200 OK Previously created request EmbeddedSignupResponse

List all requests

List sign up requests

Code samples

# You can also use wget
curl -X GET https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/ \
  -H 'Accept: application/json'

GET https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/ HTTP/1.1
Host: api.tyntec.com
Accept: application/json


const headers = {
  'Accept':'application/json'

};

fetch('https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/',
{
  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'
}

result = RestClient.get 'https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/',
  params: {
  }, headers: headers

p JSON.parse(result)

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

r = requests.get('https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/', params={

}, headers = headers)

print(r.json())

<?php

require 'vendor/autoload.php';

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

    );

$client = new \GuzzleHttp\Client();

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

try {
    $response = $client->request('GET','https://api.tyntec.com/conversations/v3/channels/whatsapp/sign-ups/', 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/conversations/v3/channels/whatsapp/sign-ups/");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
con.setRequestProperty("Accept", "application/json");

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"},

    }

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

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

GET /channels/whatsapp/sign-ups/

Lists sign up requests

Parameters

Name In Type Required Description
allOfMine query undefined false If present, returns all sign up requests made by the enterprise account

Example responses

200 Response

[
  {
    "requestId": "string",
    "countryCode": 0,
    "phoneNumber": "string",
    "profile": {
      "displayName": "string",
      "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.",
      "logoUrl": "string"
    },
    "companyDetails": {
      "companyName": "string",
      "companyAddress": "string",
      "postalCode": "string",
      "city": "string",
      "country": "string"
    },
    "pricing": {
      "selectedPlanId": 0
    },
    "status": "pending",
    "failureReason": "string",
    "whatsAppAccountId": "string",
    "apiAccountName": "string",
    "successRedirectUrl": "string",
    "failureRedirectUrl": "string",
    "statusCallbackMetaData": "string",
    "statusCallbackUrl": "string",
    "createdAt": "2020-02-15T23:28:34.442Z",
    "lastUpdated": "2020-02-15T23:28:34.442Z"
  }
]

Responses

Status Meaning Description Schema
200 OK List of previously created requests EmbeddedSignupListing

Schemas

EmbeddedSignupListing

[
  {
    "requestId": "string",
    "countryCode": 0,
    "phoneNumber": "string",
    "profile": {
      "displayName": "string",
      "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.",
      "logoUrl": "string"
    },
    "companyDetails": {
      "companyName": "string",
      "companyAddress": "string",
      "postalCode": "string",
      "city": "string",
      "country": "string"
    },
    "pricing": {
      "selectedPlanId": 0
    },
    "status": "pending",
    "failureReason": "string",
    "whatsAppAccountId": "string",
    "apiAccountName": "string",
    "successRedirectUrl": "string",
    "failureRedirectUrl": "string",
    "statusCallbackMetaData": "string",
    "statusCallbackUrl": "string",
    "createdAt": "2020-02-15T23:28:34.442Z",
    "lastUpdated": "2020-02-15T23:28:34.442Z"
  }
]

List of previously created requests

Properties

Name Type Required Restrictions Description
anonymous [EmbeddedSignupResponse] false none List of previously created requests

ISVEmbeddedSignupRequestResponse

{
  "requestId": "string",
  "redirectUrl": "string"
}

Response after a request was made

Properties

Name Type Required Restrictions Description
requestId string false none Internal request id
redirectUrl string false none Redirect URL mandatory to be used to forward a customer to the starting page on tyntec's premise for the embedded sign up process.

EmbeddedSignupResponse

{
  "requestId": "string",
  "countryCode": 0,
  "phoneNumber": "string",
  "profile": {
    "displayName": "string",
    "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.",
    "logoUrl": "string"
  },
  "companyDetails": {
    "companyName": "string",
    "companyAddress": "string",
    "postalCode": "string",
    "city": "string",
    "country": "string"
  },
  "pricing": {
    "selectedPlanId": 0
  },
  "status": "pending",
  "failureReason": "string",
  "whatsAppAccountId": "string",
  "apiAccountName": "string",
  "successRedirectUrl": "string",
  "failureRedirectUrl": "string",
  "statusCallbackMetaData": "string",
  "statusCallbackUrl": "string",
  "createdAt": "2020-02-15T23:28:34.442Z",
  "lastUpdated": "2020-02-15T23:28:34.442Z"
}

Properties

Name Type Required Restrictions Description
requestId string true none Internal request id
countryCode integer false none Country code of the phone number in activation
phoneNumber string false none Phone number in activation
profile Profile true none Profile details of the phone number. Setup after completion
companyDetails companyDetails false none Company details used on the FB BM creation throughout the process
pricing pricing true none Price plan chosen for this request. You need to use the price plan IDs available to.
status string true none Status of the request
failureReason string false none Why has the request failed
whatsAppAccountId string false none WhatsApp Account ID of the linked WhatsApp account
apiAccountName string false none Name of the API used to attach the WhatsApp Account and Phone number to
successRedirectUrl string false none To which URL should the customer be redirected after successful completion of the Embedded Sign Up process
failureRedirectUrl string false none To which URL should the customer be redirected after failed completion of the Embedded Sign Up process
statusCallbackMetaData string false none Custom meta data transferred on the asynchronous status updates on the Embedded Sign Up process
statusCallbackUrl string false none Callback URL used to deliver asynchronous status updates on the Embedded Sign Up process
createdAt string(date-time) true none At which point in time the request was created
lastUpdated string(date-time) true none At which point in time the request was updated
Enumerated values
Property Value
status pending
status facebook_connection_started
status facebook_connection_cancelled
status in_progress
status success
status failed

ISVEmbeddedSignupRequest

{
  "profile": {
    "displayName": "string",
    "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.",
    "logoUrl": "string"
  },
  "pricing": {
    "selectedPlanId": 0
  },
  "companyDetails": {
    "companyName": "string",
    "companyAddress": "string",
    "postalCode": "string",
    "city": "string",
    "country": "string"
  },
  "webhookSpecification": {
    "inboundMessageUrl": "string",
    "messageStatusUrl": "string",
    "header": {
      "key": "string",
      "value": "stringst"
    },
    "signature": {
      "secret": "stringst",
      "method": "HS256"
    }
  },
  "successRedirectUrl": "string",
  "failureRedirectUrl": "string",
  "statusCallbackMetaData": "string",
  "statusCallbackUrl": "string"
}

Embedded Sign Up Preparation Request

Properties

Name Type Required Restrictions Description
profile Profile true none Profile details of the phone number. Setup after completion
pricing pricing true none Price plan chosen for this request. You need to use the price plan IDs available to.
companyDetails companyDetails false none Company details used on the FB BM creation throughout the process
webhookSpecification webhookSpecification false none Configuration of callbacks to your system
successRedirectUrl string true none To which URL should the customer be redirected after successful completion of the Embedded Sign Up process
failureRedirectUrl string true none To which URL should the customer be redirected after failed completion of the Embedded Sign Up process
statusCallbackMetaData string false none Custom meta data transferred on the asynchronous status updates on the Embedded Sign Up process
statusCallbackUrl string true none Callback URL used to deliver asynchronous status updates on the Embedded Sign Up process

Profile

{
  "displayName": "string",
  "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.",
  "logoUrl": "string"
}

Profile details of the phone number. Setup after completion

Properties

Name Type Required Restrictions Description
displayName string true none Display name for the phone number. Used also for internal purposes
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
logoUrl string false none URL from which we can download the profile logo. Must be publicly accessible
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

pricing

{
  "selectedPlanId": 0
}

Price plan chosen for this request. You need to use the price plan IDs available to.

Properties

Name Type Required Restrictions Description
selectedPlanId integer true none ID of the price plan.

companyDetails

{
  "companyName": "string",
  "companyAddress": "string",
  "postalCode": "string",
  "city": "string",
  "country": "string"
}

Company details used on the FB BM creation throughout the process

Properties

Name Type Required Restrictions Description
companyName string false none Name of the company
companyAddress string false none Address
postalCode string false none Postal code
city string false none City
country string false none Country

webhookSpecification

{
  "inboundMessageUrl": "string",
  "messageStatusUrl": "string",
  "header": {
    "key": "string",
    "value": "stringst"
  },
  "signature": {
    "secret": "stringst",
    "method": "HS256"
  }
}

Configuration of callbacks to your system

Properties

Name Type Required Restrictions Description
inboundMessageUrl string false none Webhook for events related to inbound messages
messageStatusUrl string false none Webhook for events related to message status changes
header Header false none Additional custom header to be send with the event transmission. Can be used for setting
authentication tokens, or similar.
signature Signature false none Signature configuration for incoming events. Can be disabled by setting the
signature property to empty.

Header

{
  "key": "string",
  "value": "stringst"
}

Additional custom header to be send with the event transmission. Can be used for setting authentication tokens, or similar.

Properties

Name Type Required Restrictions Description
key string true none name of the http header
value string true none value of the http header

Signature

{
  "secret": "stringst",
  "method": "HS256"
}

Signature configuration for incoming events. Can be disabled by setting the signature property to empty.

Properties

Name Type Required Restrictions Description
secret string true none Shared secret key
method string true none cryptographic algorithm used for the signature calculation
Enumerated values
Property Value
method HS256
method HS512

Partner API Events

These section covers the events triggered throught the embedded sign up process, after the customer has completed the part of the flow with Meta.

Base URLs

production https 78.110.226.11

Server address of tyntec, the events origin from

WABA Only

Events sent out if our system detects only a WABA to register with us. This is useful, when a customer want's to migrate a phone number from the old process to a WABA managed by himself.

Success (WABA Only)

Successfull completion after an empty WABA was detected

Example payload


{
  "event": "EmbeddedSignup::WABA::Success",
  "whatsAppAccountId": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}
Properties
Name Type Required Description
event string false No description
whatsAppAccountId string false No description
Enumerated values
Property Value
event EmbeddedSignup::WABA::Success

Failure (WABA Only)

Failed completion after an empty WABA was detected

Example payload


{
  "event": "EmbeddedSignup::WABA::Success",
  "failureReason": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}
Properties
Name Type Required Description
event string false No description
failureReason string false No description
Enumerated values
Property Value
event EmbeddedSignup::WABA::Failure

Phone number

Events sent out if our system detects a request containing a registerable phone number

Success (Phone number)

Successfull completion of a phone number activation

Example payload


{
  "event": "EmbeddedSignup::WABA::Success",
  "whatsAppAccountId": "string",
  "phoneNumber": "string",
  "displayName": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}
Properties
Name Type Required Description
event string false No description
whatsAppAccountId string false No description
phoneNumber string false No description
displayName string false No description
Enumerated values
Property Value
event EmbeddedSignup::PhoneNumber::Success

Failure (Phone number)

Failed completion of a phone number activation

Example payload


{
  "event": "EmbeddedSignup::WABA::Success",
  "phoneNumber": "string",
  "failureReason": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}
Properties
Name Type Required Description
event string false No description
phoneNumber string false No description
failureReason string false No description
Enumerated values
Property Value
event EmbeddedSignup::PhoneNumber::Failure

Schemas

EmbeddedSignupEvent

{
  "event": "EmbeddedSignup::WABA::Success",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}

Properties

Name Type Required Description
event string false No description
requestId string false No description
metaData string false No description
apiAccountName string false No description
Enumerated values
Property Value
event EmbeddedSignup::WABA::Success
event EmbeddedSignup::WABA::Failure
event EmbeddedSignup::PhoneNumber::Success
event EmbeddedSignup::PhoneNumber::Failure

SuccessWABAOnly

{
  "event": "EmbeddedSignup::WABA::Success",
  "whatsAppAccountId": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}

Properties

Name Type Required Description
event string false No description
whatsAppAccountId string false No description
Enumerated values
Property Value
event EmbeddedSignup::WABA::Success

FailureWABAOnly

{
  "event": "EmbeddedSignup::WABA::Success",
  "failureReason": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}

Properties

Name Type Required Description
event string false No description
failureReason string false No description
Enumerated values
Property Value
event EmbeddedSignup::WABA::Failure

SuccessPhoneNumber

{
  "event": "EmbeddedSignup::WABA::Success",
  "whatsAppAccountId": "string",
  "phoneNumber": "string",
  "displayName": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}

Properties

Name Type Required Description
event string false No description
whatsAppAccountId string false No description
phoneNumber string false No description
displayName string false No description
Enumerated values
Property Value
event EmbeddedSignup::PhoneNumber::Success

FailurePhoneNumber

{
  "event": "EmbeddedSignup::WABA::Success",
  "phoneNumber": "string",
  "failureReason": "string",
  "requestId": "string",
  "metaData": "string",
  "apiAccountName": "string"
}

Properties

Name Type Required Description
event string false No description
phoneNumber string false No description
failureReason string false No description
Enumerated values
Property Value
event EmbeddedSignup::PhoneNumber::Failure

Business Notification API Events

The API allows you to automatically receive business notifications and updates about your account that you are using to send messages via channels.

Business Notifications are sent to your system when:

  • a channel's account is updated
  • a entity of an account is changed. Entity can be template, phone number, ...

We send notifications to your system as soon as we receive them from the channel.

For this service, you will need to provide a URL (businessNotificationUrl) at your webserver, e.g. https://rest.customer.com/businessnotification/. This URL must serve a webhook able to process POST HTTP requests, which the tyntec system will fire upon events in the system, in this case upon updates of account status or entity regarding accounts.

Supporting channels

  • Currently only whatsapp is supported

Example

Whatsapp Template status changed

- Submit your whatsapp template - Template is sent to Meta - Meta has changed status of your template (APPROVED, REJECTED, ...) - Receive info about change, together with reason and template info, on your webhook

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).

Base URLs

production https 78.110.226.11

Server address of tyntec, the events origin from

Default

business/notifications

Successfully sent notification of an account's entity updates

Inform about a change on user's channel account

Example payload


{
  "eventId": "string",
  "channel": "string",
  "entity": {
    "type": "string",
    "name": "string",
    "waba": "string",
    "language": "string",
    "phoneNumber": "string"
  },
  "changedValue": {
    "property": "string",
    "newValue": "string",
    "oldValue": "string",
    "reason": "string"
  }
}
Properties
Name Type Required Description
eventId string false Event identifier
channel string false Currently only whatsapp is supported
entity object false No description
» type string false Type of entity: template, phoneNumber, whatsapp business account, ...
» name string false Name of entity, for example template name
» waba string false If channel is whatsapp, whatsapp business account id is provided
» language string false Language of entity, for example template language
» phoneNumber string false This field exists if type is phoneNumber and represent phoneNumber of entity
changedValue object false No description
» property string false Property of entity that is changed, for example status, category,...
» newValue string false New value of property
» oldValue string false Old value of property if exists
» reason string false Reason for update

Schemas

businessNotificationEvent

{
  "eventId": "string",
  "channel": "string",
  "entity": {
    "type": "string",
    "name": "string",
    "waba": "string",
    "language": "string",
    "phoneNumber": "string"
  },
  "changedValue": {
    "property": "string",
    "newValue": "string",
    "oldValue": "string",
    "reason": "string"
  }
}

Properties

Name Type Required Description
eventId string false Event identifier
channel string false Currently only whatsapp is supported
entity object false No description
» type string false Type of entity: template, phoneNumber, whatsapp business account, ...
» name string false Name of entity, for example template name
» waba string false If channel is whatsapp, whatsapp business account id is provided
» language string false Language of entity, for example template language
» phoneNumber string false This field exists if type is phoneNumber and represent phoneNumber of entity
changedValue object false No description
» property string false Property of entity that is changed, for example status, category,...
» newValue string false New value of property
» oldValue string false Old value of property if exists
» reason string false Reason for update