Submit an inbound message
Submit a message written by one of your users and let the Shortext agent answer it.
Reply modes
sync: the request waits for the agent reply (max ~25 s) and returns it inbody.replies. On timeoutbody.statusispendingand the reply is delivered to your webhook.async: the request returns immediately withaccepted; replies are delivered to your webhook.
Idempotency: message.id is your own message id. Sending the same id again returns
duplicate with the original message, without a second reply.
Webhook: replies (async, sync timeout, human agent answers) are POSTed to the endpoint
webhook with the ShortextWebhookEvent body, signed with
X-Shortext-Signature: sha256=hex(hmac_sha256(secret, "{X-Shortext-Timestamp}.{raw_body}")).
curl --request POST \
--url https://shortext.ny-corp.io/api/messages/inbound \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"channel": "shortext",
"to": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "jsmith@example.com"
}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Ceci est un message texte.",
"preview_url": true
},
"metadata": {
"page": "/checkout"
}
},
"reply_mode": "sync"
}
'import requests
url = "https://shortext.ny-corp.io/api/messages/inbound"
payload = {
"channel": "shortext",
"to": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "jsmith@example.com"
}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Ceci est un message texte.",
"preview_url": True
},
"metadata": { "page": "/checkout" }
},
"reply_mode": "sync"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
channel: 'shortext',
to: 'ste_8k2m4q9x1v7c3n5b6z0p2r4t',
contact: {
identifier: 'user-42',
profile: {lastname: 'Awa', firstname: '<string>', email: 'jsmith@example.com'}
},
message: {
id: 'client-msg-001',
type: 'text',
content: {text: 'Ceci est un message texte.', preview_url: true},
metadata: {page: '/checkout'}
},
reply_mode: 'sync'
})
};
fetch('https://shortext.ny-corp.io/api/messages/inbound', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://shortext.ny-corp.io/api/messages/inbound",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'channel' => 'shortext',
'to' => 'ste_8k2m4q9x1v7c3n5b6z0p2r4t',
'contact' => [
'identifier' => 'user-42',
'profile' => [
'lastname' => 'Awa',
'firstname' => '<string>',
'email' => 'jsmith@example.com'
]
],
'message' => [
'id' => 'client-msg-001',
'type' => 'text',
'content' => [
'text' => 'Ceci est un message texte.',
'preview_url' => true
],
'metadata' => [
'page' => '/checkout'
]
],
'reply_mode' => 'sync'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://shortext.ny-corp.io/api/messages/inbound"
payload := strings.NewReader("{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://shortext.ny-corp.io/api/messages/inbound")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://shortext.ny-corp.io/api/messages/inbound")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"code": 1000,
"message": "Request success",
"body": {
"status": "completed",
"message": {
"id": "msg.Xk29aB",
"conversation_id": "cnv.7Hq2Lm",
"direction": "inbound",
"channel": "shortext",
"channel_id": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"identifier_type": "external_id",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "<string>",
"preferred_language": "fr"
},
"country": {}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Oui, nous livrons à Douala."
}
},
"status": "sent",
"created_at": "2023-11-07T05:31:56Z"
},
"replies": [
{
"id": "msg.Xk29aB",
"conversation_id": "cnv.7Hq2Lm",
"direction": "inbound",
"channel": "shortext",
"channel_id": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"identifier_type": "external_id",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "<string>",
"preferred_language": "fr"
},
"country": {}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Oui, nous livrons à Douala."
}
},
"status": "sent",
"created_at": "2023-11-07T05:31:56Z"
}
]
},
"token": "<string>",
"trace_id": "<string>"
}Authorizations
Company API token (Laravel Sanctum), sent as "Authorization: Bearer "
Body
Only native channels accept inbound messages
shortext "shortext"
Endpoint ID shown in the Shortext dashboard
"ste_8k2m4q9x1v7c3n5b6z0p2r4t"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Defaults to the endpoint setting
sync, async "sync"
Response
Message stored. See body.status for the reply outcome.
Standard lite-api envelope. Every endpoint answers with it; only body changes.
true
Standard response codes defined by the system / Codes de réponse standard définis par le système.
-1, -2, -3, -4, -5, 1000, -1001, -1002, -1003, -1004, -1005, -1006, -1007, -1008, -1009, -1010, -1100, -1101, -1102, -1103, 1104, -1105 1000
"Request success"
Endpoint-specific payload, null on most errors
Show child attributes
Show child attributes
Present only on authentication routes
Present only when success=false. Give it to support.
curl --request POST \
--url https://shortext.ny-corp.io/api/messages/inbound \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"channel": "shortext",
"to": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "jsmith@example.com"
}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Ceci est un message texte.",
"preview_url": true
},
"metadata": {
"page": "/checkout"
}
},
"reply_mode": "sync"
}
'import requests
url = "https://shortext.ny-corp.io/api/messages/inbound"
payload = {
"channel": "shortext",
"to": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "jsmith@example.com"
}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Ceci est un message texte.",
"preview_url": True
},
"metadata": { "page": "/checkout" }
},
"reply_mode": "sync"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
channel: 'shortext',
to: 'ste_8k2m4q9x1v7c3n5b6z0p2r4t',
contact: {
identifier: 'user-42',
profile: {lastname: 'Awa', firstname: '<string>', email: 'jsmith@example.com'}
},
message: {
id: 'client-msg-001',
type: 'text',
content: {text: 'Ceci est un message texte.', preview_url: true},
metadata: {page: '/checkout'}
},
reply_mode: 'sync'
})
};
fetch('https://shortext.ny-corp.io/api/messages/inbound', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://shortext.ny-corp.io/api/messages/inbound",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'channel' => 'shortext',
'to' => 'ste_8k2m4q9x1v7c3n5b6z0p2r4t',
'contact' => [
'identifier' => 'user-42',
'profile' => [
'lastname' => 'Awa',
'firstname' => '<string>',
'email' => 'jsmith@example.com'
]
],
'message' => [
'id' => 'client-msg-001',
'type' => 'text',
'content' => [
'text' => 'Ceci est un message texte.',
'preview_url' => true
],
'metadata' => [
'page' => '/checkout'
]
],
'reply_mode' => 'sync'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://shortext.ny-corp.io/api/messages/inbound"
payload := strings.NewReader("{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://shortext.ny-corp.io/api/messages/inbound")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://shortext.ny-corp.io/api/messages/inbound")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"channel\": \"shortext\",\n \"to\": \"ste_8k2m4q9x1v7c3n5b6z0p2r4t\",\n \"contact\": {\n \"identifier\": \"user-42\",\n \"profile\": {\n \"lastname\": \"Awa\",\n \"firstname\": \"<string>\",\n \"email\": \"jsmith@example.com\"\n }\n },\n \"message\": {\n \"id\": \"client-msg-001\",\n \"type\": \"text\",\n \"content\": {\n \"text\": \"Ceci est un message texte.\",\n \"preview_url\": true\n },\n \"metadata\": {\n \"page\": \"/checkout\"\n }\n },\n \"reply_mode\": \"sync\"\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"code": 1000,
"message": "Request success",
"body": {
"status": "completed",
"message": {
"id": "msg.Xk29aB",
"conversation_id": "cnv.7Hq2Lm",
"direction": "inbound",
"channel": "shortext",
"channel_id": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"identifier_type": "external_id",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "<string>",
"preferred_language": "fr"
},
"country": {}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Oui, nous livrons à Douala."
}
},
"status": "sent",
"created_at": "2023-11-07T05:31:56Z"
},
"replies": [
{
"id": "msg.Xk29aB",
"conversation_id": "cnv.7Hq2Lm",
"direction": "inbound",
"channel": "shortext",
"channel_id": "ste_8k2m4q9x1v7c3n5b6z0p2r4t",
"contact": {
"identifier": "user-42",
"identifier_type": "external_id",
"profile": {
"lastname": "Awa",
"firstname": "<string>",
"email": "<string>",
"preferred_language": "fr"
},
"country": {}
},
"message": {
"id": "client-msg-001",
"type": "text",
"content": {
"text": "Oui, nous livrons à Douala."
}
},
"status": "sent",
"created_at": "2023-11-07T05:31:56Z"
}
]
},
"token": "<string>",
"trace_id": "<string>"
}