Here, we'll take a look at Certainly's Trigger Message API. The Trigger Message API endpoint allows third-party applications to post messages on behalf of your Certainly bot in any active conversation, independently of the deployment channel.
cURL code
The Trigger Message API uses the following endpoint (POST):
https://app.certainly.io/actionsvc/trigger-message/
The cURL code for the request is as follows:
curl --location --request POST 'https://app.certainly.io/actionsvc/trigger-message/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dXNlcjpVU0VSX1BBU1NXT1JEX0hFUkU=' \
--data-raw '{
"text_message": "{{ENTER_MESSAGE_HERE}}",
"user_id": "{{ENTER_BOT_USER_ID_HERE}}"
}'
Authorization
The endpoint requires the use of basic authentication. To authenticate, you must do the following:
- fill the username field with the value "user"
- fill the password field with the value "bearer" + your Certainly Public API auth token
You can see an example authorization here:
username: user
password: bearer svd65ASgsDFmK7ko387GHOdkfd893ERFDlrkfERL2175POlti
You can fetch your user token by heading to the Navigation bar and clicking on "user name" when it drops down from the "My Profile" icon at the top right. There, you'll see a field named "public API auth token".
Example responses
Below you will find example responses together with their code statuses.
Successful response
Status: 200 OK
{
"message": "1",
"error": []
}
In the case of successful responses, you'll receive as a response a small JSON object that contains two keys. The first key "message" confirms that the message has been correctly triggered. The "error" key will remain as an empty array if the API call was correctly configured.
Incorrect user ID
Status: 400 Bad Request
{
"error": "Bot user with this id does not exist",
"message": null
}
Since the message was not triggered correctly here, the "message" field will return the value "null". The empty array for the error message will be replaced by a string indicating "Bot user with this id does not exist".
In these instances, remember that the bot end user's ID can be obtained using the {{certainly.from}} reserved variable.
Learn more about reserved variables.
Invalid API token
Status: 400 Bad Request
{
"error": [
{
"msg": "Invalid Authentication credentials",
"location": "Backend"
}
],
"message": null
}
Once again, since the message was not triggered correctly, the "message" field will return the value "null". In this case, the error message indicates "Invalid Authentication credentials". This is caused by using an incorrect bearer password during the authentication process.
Remember to use basic authentication and follow the steps indicated in the Authorization section of this article.