This tutorial is in order to send your first request using the version 1.0 of Sandbox Botdoc API. In order to use this version, you have to put “v1” on the API’s endpoint.
To a better understanding about the versioning, please go to api.botdoc.io/documentation/#versioning
and to a better understanding about the Sandbox, please go to api.botdoc.io/documentation/#sandbox-platform
Instructions
Inform the Token in all endpoints below:
The first thing you need to understand is every request MUST have a token:
Thus, no matter what endpoint, you always need to pass the token on the header that looks like the following:Authorization: JWT your-token-here
1 - Create a Container:
In order to create a Request, first of all, you have to make a Secure Container:
Endpoint: https://api.botdoc.io/v1/module_container/container/
Method: POST.
Example of the body in JSON format:
{
"page_type": "pushpull",
"callback_url": "https://link.to.your.callback.url"
}
Example how to create a Container by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"page_type": "pushpull",
"callback_url": "https://link.to.your.callback.url"
}"
1.2 - Create a Container with a Requester:
To create a Container with a Requester attached, is simple, first of all, you need to create a Requester, if you don't have any Requester registered, follow the link: How to create a Requester
After that, we need to create a new Container adding our Requester, the process is simple, follow:
Endpoint: https://api.botdoc.io/v1/module_container/container/
Method: POST.
Example of the body in JSON format:
{
"page_type": "pushpull",
"requester": {requester_id}
}
Example how to create a Container with a Requester by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"page_type": "pushpull",
"requester": {requester_id}
}"
Remember that, whenever a Container with a Requester attached to it is sent, the Requester is duplicated to a table RequesterContainer, to keep the data concise with the data on the day and time of the Container was sent, in case of this requester is modified or even deleted.
2 - Define Recipient(s):
After the Secure Container was created, you need to create the Recipient(s) of the Secure Container.
Endpoint: https://api.botdoc.io/v1/module_container/container/{container_id}/recipient/
Method: POST.
Example of the body in JSON format:
{
"first_name": "John",
"last_name": "Doe"
}
Example how to create a Recipient by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/{container_id}/recipient/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"first_name": "John",
"last_name": "Doe"
}
"
3 - Define your RecipientItem(s)
Now, you need to add our RecipientItem linked to the Recipient in the Step 2.
Endpoint: https://api.botdoc.io/v1/module_container/recipient/{recipient_id}/recipient_item/
Method: POST.
Example of the body in JSON format:
{
"interface_class": "email", //can be "email" or "sms"
"value": "myemail@botdoc.io"
}
Example how to create a RecipientItem by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/recipient/{recipient_id}/recipient_item/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"interface_class": "email",
"value": "myemail@botdoc.io"
}
"
4 - Set an AuthCode
Now, if you want, you can protect your Secure Container with Two Factor Authentication.
Endpoint: https://api.botdoc.io/v1/module_container/authcode/
Method: POST.
Example of the body in JSON format:
{
"container": "{container_id}",
"send_as": "email", //can be "email" or "sms"
"to": "myemail@botdoc.io"
}
Example how to create a AuthCode by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/authcode/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"container": "{container_id}",
"send_as": "email",
"to": "myemail@botdoc.io"
}"
5 - Define Email Message
Now, we must inform the Email Message if in the previewer step the transport method was sent to Email.
Endpoint: https://api.botdoc.io/v1/module_container/container/{container_id}/email/
Method: POST.
Example of the body in JSON format:
{
"subject": "nice subject",
"body": "a nice message here"
}
Example how to create an Email message by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/{container_id}/email/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"subject": "nice subject",
"body": "a nice message here"
}"
6 - Define SMS Message
Now, we must inform the SMS Message if in the previewer step the transport method was sent to SMS.
Endpoint: https://api.botdoc.io/v1/module_container/container/{container_id}/sms/
Method: POST.
Example of the body in JSON format:
{
"body": "a nice body here"
}
Example how to create an SMS message by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/{container_id}/sms/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"body": "a nice body here"
}"
7 - Add a Feature
Now, you must add a feature, can be Pull or Push see 2 examples below:
7.1 - Pull Feature
If you want to request file(s) FROM your receiver, you must send a Pull Feature:
Endpoint: https://api.botdoc.io/v1/module_container_pushpull/pushpullfeature/
Method: POST.
Example of the body in JSON format:
{
"container": "{container_id}",
"message": "Nice message inside",
"allowed_file_extensions": [
"csv", "png", "jpg", "pdf"
],
"type": "pull",
"max_files": 6
}
Example how to create an Feature Pull by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container_pushpull/pushpullfeature/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"container": "{container_id}",
"message": "Nice message inside",
"allowed_file_extensions": [
"csv", "png", "jpg", "pdf"
],
"type": "pull",
"max_files": 6
}
"
7.2 - Push Feature
If you want to SEND file(s) to your Receiver, you must send a Push Feature:
Endpoint: https://api.botdoc.io/v1/module_container_pushpull/pushpullfeature/
Method: POST.
Example of the body in JSON format:
{
"container": "{container_id}",
"message": "Nice message here",
"type": "push"
}
Example how to create an Feature Push by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container_pushpull/pushpullfeature/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw "{
"container": "{container_id}",
"message": "Nice message inside",
"allowed_file_extensions": [
"csv", "png", "jpg", "pdf"
],
"type": "push"
}
"
Media:
For files which belong to a Push, we must create in API:
{
"file": "<your file>",
"name": "image.png",
"pushpull": {pushpull_id}
}
Example of the body in JSON format:
Example how to create an Media in a Feature Push by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container_pushpull/media/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: multipart/form-data" \
--form "pushpull={pushpull_id}" \
--form "name=image.jpg" \
--form "file=@C:\images\image.png"
8 - Send the Notification to the Receiver(s)
Now, just send the Notification to the Receiver(s).
Endpoint: https://api.botdoc.io/v1/module_container/container/{container_id}/recipient/
Method: POST.
Example how to send a notification by cURL:
curl -i --request POST "https://api.botdoc.io/v1/module_container/container/{container_id}/send_notification/" \
--header "Authorization: JWT <Authorization Token>" \
--header "Content-Type: application/json" \
--data-raw ""
For more details about creating a request you can take a look at our Botdoc API Reference on api.botdoc.io/documentation/#create-request