Step 1: Request “Send a message”

To send a new, outgoing message, make a POST request to the request’s resource. The following code blocks give a basic example of how to send a message:

Basic Example for Sending a Message (JSON)

curl
-u username:password
-X POST
-H "Content-Type: application/json"
-d ‘{
"from":"MyCompany",
"to":"+491622943176",
"message":"This is an example."
}’
https://rest.tyntec.com/messaging/im/v1/outbound/requests

Response to Basic Example for Sending a Message (JSON)

HTTP/1.1 200 OK
{
"requestId":"12-75cfafba-8799-4f2b-8505-ece6af6abf01",
"errorText":""
}

In this request, there are a number of parameters that need to be defined, while others are optional:

Parameter

Optional/ Mandatory

Possible Values

Description

from

mandatory

any international phone

number OR short code OR alphanumeric

sender ID (1-11 characters)

This parameter gives the identification of the sending party, which can either be the phone number in international format or a short code, or an alphanumeric identifier with up to 11 characters.

When the message is sent to a messaging app, a predefined name identifying your service may be used instead of this field. When the message is sent via SMS, some destination networks impose restrictions on the sender ID format. Please check the coverage list and/or contact your account manager for more information.

to

mandatory

any international phone

number

This parameter represents the receiving party’s phone number in international format.

message

optional

any UTF-8 encoded

string

The message will be delivered as such to messaging apps. When delivered via SMS, the maximum length is 70 characters per single message and 63 characters per concatenated message.

imageUrl

optional

any valid URL maximum 62 characters long

If this parameter is present, the image URL is sent to the messaging app and if supported by it, displayed. If the message falls back to SMS, the URL is included in the message.

buttonActionUrl

optional

any valid URL maximum 62 characters long

This parameter controls which action should be executed, when the receipient clicks on the button.

buttonCaption

optional

any UTF-8 encoded string

This parameter controls which text is displayed on the button in a messaging app.

imChannels

optional

“FACEBOOK”, “VIBER”,   “FACEBOOK, VIBER”,   “VIBER, FACEBOOK”

This parameter enables to specify the IM channels the system will attempt to deliver the messages to and in which order. It can be “FACEBOOK”, “VIBER”, “FACEBOOK , VIBER” or “VIBER , FACEBOOK”. The system will attempt to the deliver  to the next messaging app only in case the message cannot be delivered to the previous one. If not specified, the default order is “VIBER , FACEBOOK”. Please note that the SMS fallback is controlled by “deliverOnlyViaIM” parameter.

deliverOnlyViaIM

optional

true/false

If this parameter is set to “true”, the fallback to SMS is deactivated. The message will be attempted only via IM and will fail if it cannot be delivered to one of the supported messaging apps.

ttl

optional

any positive integer value

The message validity period in seconds. While tyntec does not impose a minimum ttl, some messaging apps might ignore a ttl value lower than a certain threshold. ttl range: 15 - 86400 seconds. If it is not set,  the default is 14 days.

 

Supported by: Viber, SMS

ttlExpiryText

optional

any UTF-8 encoded

string

If this parameter is defined and supported by the destination messaging app, the user will see this text instead of the original text defined in the message parameter in case the message is delivered after the expiration of the ttl.

 

Supported by: Viber

 

*Relevant for iOS only. For Android, if the message was not delivered before the time ended, the message will not appear.

callbackUrl

optional

any UTF-8 encoded string

We will use this URL to submit the delivery receipts to you. The following scenarios are possible:

  1. You have the option to define the callback ULR as a global parameter by asking tyntec Support. If you do this, you don’t need to specify the callback URL in each request. If you do specify it in the request though, it overrides the default.
  2. You can choose not to define a global callback URL, and then you need to specify it in every request.
  3. If you don’t define the global URL and you also don’t define the callbackURL parameter, tyntec will not send the delivery receipts to you.

messagePurpose

mandatory

"promotion" or "transaction"

This parameter is mandatory when sending messages to Viber.

 

 

Viber

Message length (characters)

1,000

Button caption length (characters)

30

Message types

Text only

yes

Image only

yes

Text + image

no

Text + button

yes

Image + button

no

Text + image + button

yes