Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1034 lines (997 sloc) 33 KB
openapi: '3.0.0'
info:
title: Chat API
description: |
The Chat API enables you to easily send messages to your customers via messaging services like WhatsApp or
Viber and still address customers with classic SMS.
In addition you can define a chain of channels which will be used for messaging attempts until one succeeds.
Notifications and messages from your users are send by us to your system via HTTP ```POST``` method.
contact:
name: tyntec API Support
url: http://www.tyntec.com/support
email: support@tyntec.com
version: '2.3'
x-repository: https://github.com/tyntec/api-collection/blob/master/chat-api
x-major-version: v2
x-postman-collection: postman.zip
servers:
- url: https://api.tyntec.com/messaging/v2/chat
security:
- ApiKeyAuth: []
tags:
- name: "Send messages"
description: |
In this section we guide you on how to send messages, get information about the status and the events happening
during the delivery
- name: "Receive messages"
description: |
In order to receive messages send by the user you need to configure first an public available endpoint.
We will use HTTP ```POST``` method to send the user messages to your system as defined in MoMessage.
Media send by the user can be downloaded by
- either by following the link in the MoMedia object or
- by using the received media id and query our system via _/media/{media-id}_ (see below)
- name: "Notifications"
description: |
Notifications or DLRs are **send** to your system when
- a message reaches a final state or
- a user decides to delete a message previously send **to** you.
We treat
- delivered
- seen / read
- finally failed
as final states for message send by you.
We will use HTTP ```POST``` method to send the notifications to your system.
The notification message is the same as for the message status you can query MessageStatus.
paths:
/messages:
post:
operationId: sendMessage
summary: Send a message
tags:
- "Send messages"
description: Send chat messages via this path.
requestBody:
description: The message you would like to send
required: true
content:
'application/json':
schema:
$ref: '#/components/schemas/MessageRequest'
responses:
'202':
description: The message is accepted by our system
content:
'application/json':
schema:
$ref: '#/components/schemas/MessageResponse'
'400':
description: The request does not match our expectations. Please check the Problems object for details
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
default:
description: For all other error cases please check the problem object
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
/messages/{message-id}:
get:
operationId: retrieveMessage
summary: Retrieve the message
tags:
- "Send messages"
description: |
Returns back a message previously send by you.
**Please note** After a final status notification (delivered, read or failed) the message
is only available for the next 48 hours. After this period we delete the message in our system.
parameters:
- name: message-id
in: path
required: true
description: The id of the message
schema:
type: string
format: uuid
example: 77185196-664a-43ec-b14a-fe97036c697f
responses:
'200':
description: The message id requested exists.
content:
'application/json':
schema:
$ref: '#/components/schemas/StoredMessage'
'404':
description: The message id does not exists in our system
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
default:
description: For all other error cases please check the problem object
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
/messages/{message-id}/history:
get:
operationId: getMessageHistory
summary: View message history
tags:
- "Send messages"
description: |
Get the history of the message.
This will give you detailed information about the delivery flow of the message.
parameters:
- name: message-id
in: path
required: true
description: The id of the message
schema:
type: string
format: uuid
example: 77185196-664a-43ec-b14a-fe97036c697f
responses:
'200':
description: The history of the message id.
content:
'application/json':
schema:
$ref: '#/components/schemas/MessageHistory'
'404':
description: The message id does not exists in our system
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
default:
description: For all other error cases please check the problem object
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
/media/{media-id}:
parameters:
- name: media-id
in: path
required: true
description: The id of the media to be downloaded
schema:
type: string
format: uuid
example: 77185196-664a-43ec-b14a-fe97036c697f
get:
operationId: downloadMedia
summary: Download received media
tags:
- "Receive messages"
description: Retrieve the media associated with the id
responses:
'200':
description: The media associated with the id requested exists.
content:
'audio/*':
schema:
type: string
format: binary
'application/*':
schema:
type: string
format: binary
'text/*':
schema:
type: string
format: binary
'video/*':
schema:
type: string
format: binary
'404':
description: The media associated with the id does not exists in our system
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
default:
description: For all other error cases please check the problem object
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
/messages/{message-id}/status:
get:
operationId: checkMessageStatus
summary: Check message status
tags:
- "Notifications"
description: Check status of the message
parameters:
- name: message-id
in: path
required: true
description: The id of the message
schema:
type: string
format: uuid
example: 77185196-664a-43ec-b14a-fe97036c697f
responses:
'200':
description: The message id requested exists.
content:
'application/json':
schema:
$ref: '#/components/schemas/MessageStatus'
'404':
description: The message id does not exists in our system
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
default:
description: For all other error cases please check the problem object
content:
'application/json':
schema:
$ref: '#/components/schemas/Problem'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: apikey
schemas:
MessageRequest:
type: object
description: The message you would like to send
required:
- to
- channels
properties:
to:
type: string
pattern: '^(00|\+)\d{1,15}$'
description: |
The receipient phone number in international format. It should follow the guidelines
of [E.164](https://en.wikipedia.org/wiki/E.164) but leading 00 is as well accepted
example: "+1233423454"
channels:
type: array
description: Channels selected for delivery.
example:
- sms
- whatsapp
items:
type: string
enum:
- sms
- whatsapp
- tyntecEcho
overrides:
$ref: '#/components/schemas/MessageRequestOverrides'
context:
$ref: '#/components/schemas/MessageRequestContext'
defaultContent:
$ref: '#/components/schemas/DefaultContent'
sms:
$ref: '#/components/schemas/SMSRequest'
whatsapp:
$ref: '#/components/schemas/WhatsappMessageRequest'
tyntecEcho:
description: |
This channel can be used for integration purposes without sending any message to an actual device.
A detailed description is provided on the object definition.
allOf:
- $ref: '#/components/schemas/TyntecEchoRequest'
example:
to: "+123234234"
channels: ["whatsapp"]
whatsapp:
from: "545345345"
contentType: text
text: A simple text message
StoredMessage:
type: object
required:
- to
- channels
properties:
to:
type: string
pattern: '^(00|\+)\d{1,15}$'
description: |
The receipient phone number in international format. It should follow the guidelines
of [E.164](https://en.wikipedia.org/wiki/E.164) but leading 00 is as well accepted
example: '+1233423454'
channels:
type: array
description: Channels selected for delivery.
example:
- sms
- whatsapp
items:
type: string
enum:
- sms
- whatsapp
- tyntecEcho
sms:
$ref: '#/components/schemas/SMSRequest'
whatsapp:
$ref: '#/components/schemas/WhatsappMessageRequest'
tyntecEcho:
description: |
This channel can be used for integration purposes without sending any message to an actual device.
A detailed description is provided on the object definition.
allOf:
- $ref: '#/components/schemas/TyntecEchoRequest'
example:
messageId: 77185196-664a-43ec-b14a-fe97036c697f
to: "+123234234"
channels: ["whatsapp"]
whatsapp:
from: "545345345"
contentType: text
text: A simple text message
DefaultContent:
description: |
The default content that is applied to all channels.
Each component might be overrwritten or extended by channel specific settings.
This can be used to specify the text for a message once, but the _from_ per used channel.
type: object
required:
- contentType
- from
properties:
from:
type: string
description: The sender of the message
example: "1233423454"
contentType:
type: string
enum:
- template
- text
- url
- media
description: What kind of payload is used
example: template
text:
type: string
description: The text to be send
example: Thanks for contacting our support. We will get back to you in 5 minutes.
url:
type: string
description: the URL you would like to send. Must be a valid http(s) URL
example: https://www.tyntec.com
media:
$ref: '#/components/schemas/Media'
template:
$ref: '#/components/schemas/Template'
example:
from: "1233423454"
contentType: template
template:
templateId: welcome_message
language:
policy: deterministic
code: en
parameters:
- default: Mr. Doe
SMSRequest:
type: object
description: |
Normal SMS to be send.
If Content is used as well this will override the specification made there.
In case URL type is specified the recipient will receive the plain URL as SMS.
required:
- contentType
properties:
contentType:
type: string
enum:
- text
- url
description: What kind of payload should be sent
example: text
from:
type: string
description: The sender of the message
example: "1233423454"
text:
type: string
maxLength: 3000
description: The message to be send
example: Thanks for contacting our support. We will get back to you in 5 minutes.
url:
type: string
description: the URL you would like to send. Must be a valid http(s) URL
example: https://www.tyntec.com
example:
contentType: text
from: "1233423454"
text: Thanks for contacting our support. We will get back to you in 5 minutes.
WhatsappMessageRequest:
description: |
Whatsapp message to be send.
This will override defaults from DefaultContent
type: object
required:
- contentType
- from
properties:
from:
type: string
description: The sending whatsapp account
example: "1233423454"
contentType:
type: string
enum:
- template
- text
- url
- media
description: What kind of payload is used
example: template
text:
type: string
maxLength: 4096
description: The text to be send
example: Thanks for contacting our support. We will get back to you in 5 minutes.
url:
type: string
description: the URL you would like to send. Must be a valid http(s) URL
example: https://www.tyntec.com
media:
$ref: '#/components/schemas/Media'
template:
$ref: '#/components/schemas/Template'
example:
from: "1233423454"
contentType: media
media:
type: audio
url: 'https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.svg'
caption: Tyntec Logo
TyntecEchoRequest:
type: object
description: |
This channel can be used for integration purposes without sending any message to an actual device.
It has two modes
- only send the delivered dlr back
- send additionally a message back
The messages send back follow these rules :
- media, text and url are send back as they are
- templates are formatted as
`TemplateId[templateId] LanguagePolicy[language.policy] LanguageCode[language.code] Parameter<N>[parameters[N]]`
- from and to switch positions
- messageId will be the same as for the request
required:
- contentType
- from
properties:
from:
type: string
description: The sending tyntecEcho account
example: "1233423454"
contentType:
type: string
enum:
- template
- text
- url
- media
description: What kind of payload is used
example: template
text:
type: string
maxLength: 100
description: The text to be send
example: Thanks for contacting our support. We will get back to you in 5 minutes.
url:
type: string
description: the URL you would like to send. Must be a valid http(s) URL
example: https://www.tyntec.com
media:
$ref: '#/components/schemas/Media'
template:
$ref: '#/components/schemas/Template'
replyBack:
type: boolean
description: Should the channel reply back the send message
default: false
example:
from: "1233423454"
contentType: url
url: 'https://www.tyntec.com'
replyBack: false
Media:
type: object
description: Media to be send
properties:
type:
type: string
description: What kind of media should be send
enum:
- image
- document
- audio
- video
example: image
url:
type: string
description: the url of the location where the media is stored
example: https://www.tyntec.com/themes/custom/tyntec/image/tyntec-logo-color.svg
caption:
type: string
description: additional caption for the media. is shown on the uploaded media when the channel supports this
example: Tyntec Logo
Template:
type: object
description: The message template to be send.
required:
- templateId
- language
properties:
templateId:
type: string
description: the identifier of the template that should be used
example: welcome_message
language:
$ref: '#/components/schemas/Language'
parameters:
description: Parameter for replacement in the template.
type: array
items:
$ref: '#/components/schemas/TemplateParameter'
Language:
type: object
description: Language settings for the template
properties:
policy:
type: string
description: Used for multi-language template resolution.
enum:
- fallback
- deterministic
default: deterministic
code:
description: |
The code of the language or locale to use —
Accepts both language and language_locale formats (e.g., en and en_US).
type: string
example: en
TemplateParameter:
type: object
description: |
Parameter for replacement in the template.
The value can contain any character except of :
- newline
- tabulator
- more then 4 consecutive spaces.
It can be formatted accordingly to [Formatting your messages](https://faq.whatsapp.com/en/android/26000002/?fbclid=IwAR1-VtKzKAxleQD-nnWbZpIhLtkNY6Hpjjb4echlEmcfLV2l0C5We4HnsUM).
properties:
default:
type: string
description: Variable substitution.
example: Mr. Doe
MessageResponse:
type: object
required:
- messageId
- acceptedAt
properties:
messageId:
type: string
format: uuid
description: Global Message Id reference
example: 77185196-664a-43ec-b14a-fe97036c697f
acceptedAt:
type: string
format: date-time
description: Point in time when the Chat API service confirms that the message request was accepted
MessageStatus:
type: object
description: |
The current status of a message.
It is used for messages send and received by you.
In case you send a message the status will inform you about the delivery process.
In the case that you receive a message from a user, the user may decide to delete the message.
Then and only then status deleted is triggered.
required:
- messageId
- status
properties:
messageId:
type: string
description: Global Message Id reference
example: 77185196-664a-43ec-b14a-fe97036c697f
deliveryChannel:
type: string
description: Channel which was used for delivery
example: sms
enum:
- sms
- whatsapp
- tyntecEcho
status:
description: Indicates the status of the message. Be aware that not all channels support all status.
type: string
example: seen
enum:
- accepted
- delivered
- seen
- failed
- unknown
- deleted
timestamp:
type: string
format: 'date-time'
description: Point in time when the event happend
example:
2019-06-26T11:41:28Z
userContext:
type: string
description: Contextual information set on the message request
example:
my-message-reference
example:
messageId: 77185196-664a-43ec-b14a-fe97036c697f
deliveryChannel: whatsapp
status: seen
userContext: my-message-reference
timestamp: 2019-06-26T11:41:28Z
MessageHistory:
type: object
properties:
messageId:
type: string
format: uuid
description: Global Message Id reference
example: 77185196-664a-43ec-b14a-fe97036c697f
userContext:
type: string
description: Contextual information set on the message request
example:
my-message-reference
history:
type: array
description: Ordered list of current available events for your message
items:
$ref: '#/components/schemas/HistoryItem'
example:
messageId: 77185196-664a-43ec-b14a-fe97036c697f
userContext: my-message-reference
history:
- deliveryChannel: whatsapp
happendAt: '2019-03-13T12:57:27.048Z'
state: accepted
HistoryItem:
type: object
description: Contains information about a specific event occuring in the delivery process
properties:
deliveryChannel:
type: string
description: The channel triggering this event
example: whatsapp
enum:
- sms
- whatsapp
- tyntecEcho
happendAt:
type: string
description: When did the event happen
format: date-time
state:
type: string
description: State of the message delivery
example: accepted
enum:
- accepted
- dispatched
- dispatching_failed
- success
- failed
- unknown
details:
$ref: '#/components/schemas/HistoryDetails'
example:
deliveryChannel: whatsapp
happendAt: '2019-03-13T13:15:22Z'
state: accepted
HistoryDetails:
description: Further information available for this event
type: object
additionalProperties: true
properties:
code:
type: string
description: Code specific to the details
example: tyntec::error:noFurtherChannelAvailable
message:
type: string
description: Textual representation of the code, containing further information
example: No further channel after Channel[whatsapp] available
Problem:
type: object
additionalProperties: true
description: The problem object follows the RFC-7807 (https://tools.ietf.org/html/rfc7807)
required:
- type
- title
- status
- detail
properties:
type:
description: A URI reference [RFC3986] that identifies the problem type
example: https://docs.tyntec.com/problems/DataNotParseable
type: string
title:
type: string
example: Data given was not parseable
description: A short, human-readable summary of the problem type.
status:
description: The HTTP status code (RFC7231, Section 6) generated by the origin server for this occurrence of the problem.
type: string
example: 400
detail:
description: A human-readable explanation specific to this occurrence of the problem.
type: string
example: |
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]
MoMessage:
type: object
description: |
Message received by us and delivered to your system via a webhook provided by your system.
MoMessages are transferred by using HTTP ```POST``` method.
required:
- messageId
- channel
- from
- content
properties:
messageId:
type: string
description: Message Id reference
example: 77185196-664a-43ec-b14a-fe97036c697f
from:
type: string
description: the sender of the message
example: "49123512314"
to:
type: string
description: Receiving account of the message. The format is channel specific
example: "49123512314"
channel:
type: string
description: Channel which delivered the message to us
example: sms
enum:
- sms
- whatsapp
- tyntecEcho
content:
$ref: '#/components/schemas/MoContent'
context:
$ref: '#/components/schemas/MoContext'
sms:
$ref: '#/components/schemas/SMS'
whatsapp:
$ref: '#/components/schemas/Whatsapp'
example:
messageId: 77185196-664a-43ec-b14a-fe97036c697e
from: "49123512314"
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
MoContent:
type: object
description: Content of the mobile originated message
required:
- contentType
properties:
contentType:
type: string
enum:
- text
- url
- media
description: What kind of payload is used
example: media
text:
type: string
description: The received text
example: hi, thanks for your support message
url:
type: string
description: the URL received
example: https://www.tyntec.com
media:
$ref: '#/components/schemas/MoMedia'
example:
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
MoContext:
type: object
description: Contextual information of the mobile originated message
properties:
messageId:
type: string
description: The message id the MoMessage refers to. Usualy set when the sender replies to a specific message
example: 77185196-664a-43ec-b14a-fe97036c697a
MoMedia:
type: object
description: Media information
properties:
type:
type: string
description: What kind of media was received
enum:
- image
- document
- audio
- voice
- video
example: audio
url:
type: string
description: the url of the location where the media is stored
example: https://api.tyntec.com/messaging/v1/chat/media/77185196-664a-43ec-b14a-fe97036c697f
mediaId:
type: string
description: plain id of the media to download
example: 77185196-664a-43ec-b14a-fe97036c697f
caption:
type: string
description: caption specified by the user or the file name of the document
example: This is an picture of my cat!
SMS:
type: object
description: specifics of the sms channel
properties:
origin:
$ref: '#/components/schemas/SMSOrigin'
totalPrice:
type: number
description: The sum of prices for each message part listed in “contentList”.
example: 0.1
size:
type: number
description: The amount of respective concatenated SMS parts.
minimum: 1
maximum: 255
example: 1
missingParts:
type: boolean
description: True in case a part of an over-length was not received by the tyntec platform and the forwarded message text is incomplete.
default: false
example: false
parts:
type: array
description: |
tyntec merges over-length (concatenated) SMS into one string before sending it to your webserver.
Information for each individual part are collected here
items:
$ref: '#/components/schemas/SMSContent'
example:
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
SMSOrigin:
type: object
description: Origin Information of the message
properties:
mcc:
type: string
description: A representative MCC (Mobile Network Code) of the originating network.
example: "49"
mnc:
type: string
description: A representative MNC (Mobile Network Code) of the originating network.
example: "176"
ttId:
type: string
description: The respective tyntec ID of the originating network.
example: "25"
SMSContent:
type: object
description: SMS channel specific information
properties:
messageId:
type: string
description: The unique identifier provided by tyntec for each message part.
example: 48514285-4e78-4eef-b0c6-4ce68d40c1c3
sentDate:
type: string
description: |
The time stamp when the SMS has been received by the sending MSC (if available).
or
The time stamp when the respective message was received by tyntec.
format: date-time
price:
type: number
description: |
The price per message from the respective network.
Negative prices represent payout in favor of tyntec’s customer.
example: 0.1
currency:
type: string
description: The currency in which the pricing is given; corresponding to the currency of the invoice.
example : EUR
priceEffective:
type: string
description: The date when the “price” became effective.
format: date-time
sequenceNumber:
type: number
description: |
In case an over-length message is received tyntec recomposes the full message text before forwarding.
The “sequenceNumber” indicates the order of the message part.
minimum: 1
maximum: 255
example: 1
Whatsapp:
type: object
description: specifics of the whatsapp channel
properties:
senderName:
type: string
description: Name of the sender, set in his or her profile
example: Peter
example:
senderName: Peter
additionalProperties: true
MessageRequestContext:
type: object
description: Contextual information for the message request
properties:
userContext:
type: string
maxLength: 255
description: |
Contextual information that is transfered back on delivery notifications.
example:
my-message-reference
MessageRequestOverrides:
type: object
description: Overrides of defaults for this message
properties:
notificationCallbackUrl:
type: string
pattern: ^https:\/\/?[\w.-]+(?:\.[\w\.-]+)+[\w\-\._~:/?#[\]@!\$&'\(\)\*\+,;=.]+$
description: |
When present this url is used for sending the delivery notifications to your webhook.
Can be used for debugging use cases or individual routings.
example:
https://en4u5fpprib5i.x.pipedream.net
You can’t perform that action at this time.