send/v1

Send SMS, Email, Link-SMS, MMS, Fax messages

RESTful style

New prettier version of documentation, OpenApi format

(Temporary location, don't bookmark, will move to tellustalk.com site soon)

--------------------------------------------------------------------------------------------------------------------------------------------------------------------

Request Headers and Response Format

Host URL: https://api.tellustalk.com/send/v1

Request Method

POST

Request Headers:

Content-Type: application/json (recommended), application/xml, or application/x-www-form-urlencoded

Authorization: Basic username:password (base64-encoded)

Response:

If successful, HTTP status code is 200 (OK)

Response data has one item (in the accepted format)

job_id: The id of the request, to use with /logs/v1

If failed: A HTTP status code and possibly an explaining text.

---------------------------------------------------------------------------------------------------------------------------------------------------------------------

Request BODY:

A message with a few required and several optional values formatted as JSON (preferred) or XML.

Basic options shown below. For more options, see Rest Api Dictionary.

Request Examples

Example (Simplest):

Example (More than one recipient, with attachments):

Request Header

Content-Type: application/json

Basic: dXNlcm5hbWU6cGFzc3dvcmQ=

Content-Type: application/xml

Basic: dXNlcm5hbWU6cGFzc3dvcmQ=

Request Body

{

"to": ["sms:+46704000000", "email:test.user@mycompany.com"],

"subject": "A small flower!",

"text": "Hello!",

"html": "<b>This message</b> is nicely formatted.",

"attachments": [{

"name": "lotus.jpg",

"href": "data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAw

AAAC8IyPqcvt3wCcDkiLc7C0qwyGHhSWpjQu5yqmCYsapyuvUUlvONmOZtfzgFz ByTB10QgxOR0TqBQejhRNzOfkVJ+5YiUqrXF5Y5lKh/DeuNcP5yLWGsEbtLiOSp a/TPg7JpJHxyendzWTBfX0cxOnKPjgBzi4diinWGdkF8kjdfnycQZXZeYGejmJl ZeGl9i2icVqaNVailT6F5iJ90m6mvuTS4OK05M0vDk0Q4XUtwvKOzrcd3iq9uis F81M1OIcR7lEewwcLp7tuNNkM3uNna3F2JQFo97Vriy/Xl4/f1cf5VWzXyym7PH

hhx4dbgYKAAA7"

}]

}

<?xml version="1.0" encoding="ISO-8859-1"?>

<root>

<to>email:test.user@mycompany.com</to>

<subject>A small flower!</subject>

<html><b>This message</b> is nicely formatted and properly escaped.</html>

<name>lotus.jpg</name>

<href>data:image/gif;base64,R0lGODdhMAAwAPAAAAAAAP///ywAAAAAMAAw

hhx4dbgYKAAA7

</href>

</attachments>

</root>

Required Message Parameters:

Optional Message Parameters:

Attachments:

Attachments can be sent via Link SMS, fax or email.

Secure Messaging and Signatures

Secure messages and signature requests can be sent, simply by appending parameters in addressing.

More options for Sign/Login

The sign_options struct has additional values used in the login or signing process.

All values are optional.

Use the html_... options only if you want to do the extra work to make things more in line with your graphical style.

Two variants of signatures: PDF or just text

A proper contract should be submitted as PDF. This is standard for legal agreements.

Informal "signing off" on a shorter text is also possible, just submit the agreement as a plain message text.

The signature file is still a PDF with electronic seal, sign service info etc, but the full agreement is visible directly when signing.

Attachment file: Sign PDF file(s). TellusTalk will attempt to combine multiple files into a single PDF. It is faster and more reliable to send a single file.

"Simple" plain text: This must be in the "text" field in the message. If HTML is included, it is used only for presentation.

Custom styling of login /sign interface

If you want a different design from our functional default view, create a <style> CSS section in your HTML message.

This affects the main signature or protected message frame.

LOGIN PROCESS - where to put my CSS?

html_login_page: The front page shown before login.

public_message text is shown, + your CSS in html_login_page

html_login_client: The page shown during login, after they click Login button

html / the actual message: Shown after finished login.

If this is a protected signature, go to the first step of sign process below.

SIGN PROCESS - where to put my CSS?

html / the presentation message: Shown on the signature front page.

If there is a PDF to sign, most of the message may be hidden (shown by View Info button), but CSS is effective

If they should sign text only, this text is displayed. Your html could be just the CSS.

html_login_client: The page shown during signature, after they click Sign button

html_success: The signature page after finished signature. This replaces your html message completely.

What CSS values to override?

Look for the CSS classes with prefix tt-

Create a signature/protected message job, then use View Source in your browser and look for all CSS classes with prefix tt-, eg:

tt-reply-button

tt-block-button

tt-logout-button

tt-bottom-box

etc

More can be added as required.

Payments

Payment requests can be sent via SMS, Email.

There is also an API for direct use (ie without sending a message), see shopping_cart/v1

Redirect to sign/login from your website

This is used to start a job when you handle communication with the end user, eg

present the job link directly on your website
- send the job link via your own mail system or other messaging channel

REQUEST

In the to field, use protocol log:, instead of address put your own string (an application id or your internal job id)

Example:

{

"to": ["log:yoursearchkey.sign"],

"text": "Please sign this simple test text!"

}

This example allows anyone to view and sign.

Normally you would specify personal ID on each login/sign:

{ "to": ["log:anystring.login199101012020.sign199101012020",

"sms:0760000000.login200111223030.sign200111223030"],

...}

Multiple recipients (max 5) are allowed in the log: redirect api requests.

anystring/yoursearchkey may be used as search key in our logs, to identify your different applications, or your internal job id.

anystring can be alphanumeric, an email address or almost anything without ? or & chars

RESPONSE

When you send to log: the HTTP response body includes the value log_href:

{

"job_id": "12345678",

"log_href": "https://ebox.nu/z_123code"

}

Use the log_href value for a redirect on your web page, the user is sent directly to our login and/or sign pages.

We store the job before the /send/v1 call returns to you.

So you can redirect your users to the ebox page immediately without showing a clickable link.

NOTE: This feature works with only a few recipients (max 5) in a single message.

Integrate using Wordpress Gravity Forms - contact us at support@tellustalk.com for documentation.

Cookie-free browsing!

When you embedd a request to tellustalk from your own site inside an IFRAME, cookies are not propagated in some browsers (notably Safari).

To get around this, put /nocookie/ first in the tellustalk redirect URL path, eg:

https://ebox.nu/nocookie/z_requestcode

https://ebox.nu/nocookie/payment/shopping_cart/v1.htm

etc.

When end user clicks or is redirected to the link, the /nocookie part is replaced with a session key that works like a cookie.