--- title: Engati APIs slug: engati-apis docTags: createdAt: 2022-05-23T13:22:43.000Z --- # **Introduction** Engati APIs allow you to integrate with the platform and create useful functionality around the platform. The APIs are REST-based using JSON as the standard response type. **Headers ** API Keys need to be added to the Authorization header as follows – `Authorization : Basic ` - The API Keys can be generated by going to [Engati API](https://agents.engati.ai/admin/integrations/platform-api) section. - Engati APIs follow basic authentication utilizing API Keys to authenticate the API calls. - The API Keys can be revoked or regenerated at any point in time and would throw authentication errors for the API calls made using them. :::ApiMethodV2 ```json { "tab": "examples", "url": "https://api.engati.ai", "name": "Engati APIs", "method": "POST", "request": { "pathParameters": [], "queryParameters": [], "headerParameters": [], "bodyDataParameters": [], "formDataParameters": [] }, "results": { "languages": [ { "id": "keltcMNS8tbZ5b30BmdY-", "code": "{\n \"responseObject\": true\n}", "language": "200", "customLabel": "" }, { "id": "AW-Tt2Mo1dwCGf_4c9XWP", "code": "{\n \"message\": \"Ain't no cake like that.\"\n }", "language": "404", "customLabel": "" } ], "selectedLanguageId": "keltcMNS8tbZ5b30BmdY-" }, "examples": { "languages": [ { "id": "S6zZPicp_Khm_KLwsHa4f", "language": "curl", "code": "curl --location --request GET 'https://api.engati.ai/bot-api/v1.0/customer/61179/bot/bb67e0773bed4c7e/users?attribute_name=opt1&attribute_value=yes' \\\n--header 'Authorization: Basic 2082e8f4-0011-479b-9edb-74293c62d91b-GkOuZiq' \\\n--header 'Content-Type: application/json' \\\n--data-raw ''", "customLabel": "Users" }, { "id": "ATvKD-tpYG-DOQFOF92bZ", "language": "curl", "code": "curl --location --request GET 'https://api.engati.ai/bot-api/v1.0/customer/61179/bot/bb67e0773bed4c7e/channel-user/919565428256/conversations' \\\n--header 'Authorization: Basic 2082e8f4-0011-479b-9edb-74293c62d91b-GkOuZiq' \\\n--header 'Content-Type: application/json' \\\n--data-raw ''", "customLabel": "Conversation History" }, { "id": "YbcwzhFmluYXoAdHW1AP-", "language": "curl", "code": "curl --location --request POST 'https://api.engati.ai/whatsapp-api/v1.0/customer/49373/bot/f5afdd1c000742f0/template' \\\n--header 'Authorization: Basic 1b051089-77b5-4a97-ad8e-f3186a6a7532-FqXcFmW' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"phoneNumber\": \"+919019486731\",\n \"payload\": {\n \"components\": [\n {\n \"type\": \"header\",\n \"parameters\": [\n {\n \"type\": \"document\",\n \"document\": {\n \"filename\": \"uribapplicationform_82121086.pdf\",\n \"link\": \"https://s3.ap-south-1.amazonaws.com/file-upload-public/prod/61179/BROADCAST_TEMPLATE_ATTACHMENT/75549-uribapplicationform_82121086.pdf\"\n }\n }\n ]\n },\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"John\"\n },{\n \"type\": \"text\",\n \"text\": \"John\"\n },{\n \"type\": \"text\",\n \"text\": \"John\"\n }\n ]\n },\n {\n \"index\": 0,\n \"parameters\": [\n {\n \"payload\": \"flow_7BBB608C3B4B4E848F36CD2CCD7CFA35||data_PersonX_response=Declined_Invoice_no_12345\",\n \"type\": \"payload\"\n }\n ],\n \"sub_type\": \"quick_reply\",\n \"type\": \"button\"\n },\n {\n \"index\": 1,\n \"parameters\": [\n {\n \"payload\": \"flow_E30D44BCCA4C49D49976D3AC0416C405||data_PersonX_response=Approved_Invoice_no_12345\",\n \"type\": \"payload\"\n }\n ],\n \"sub_type\": \"quick_reply\",\n \"type\": \"button\"\n }\n ],\n \"namespace\": \"980c3243_2d2a_4d2d_a572_b2a50552cb04\",\n \"name\": \"renuka_sugars_paytest\",\n \"language\": {\n \"policy\": \"deterministic\",\n \"code\": \"en\"\n }\n }\n}\n}'", "customLabel": "Whatsapp Broadcast" }, { "id": "sNoTMB7v7mbA2Uurq2m10", "language": "json", "code": "curl --location --request POST 'https://api.engati.ai/bot-api/v1.0/customer/61179/bot/bb67e0773bed4c7e/broadcast' \\\n--header 'Authorization: Basic 2082e8f4-0011-479b-9edb-74293c62d91b-GkOuZiq' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n\"broadcastId\": null,\n\"broadcastTitle\": \"testing broadcast\",\n\"publishedOn\": \"2019-06-03T06:48:27.170Z\",\n\"audience\": {\n\"rule\": {\n\"channels\":[\"whatsapp\"],\n\"channelUserIds\":[\"919019486731\"]\n}\n},\n\"payload\": {\n\"type\": \"DIRECT\",\n\"content\": [\n{\n\"type\": \"TEXT\",\n\"data\": {\n\"message\": \"This is a test message\"\n}\n},\n{\n\"type\": \"TEXT\",\n\"data\": {\n\"message\": \"This is another message\"\n}\n}\n]\n},\n\"status\": null\n}\n'", "customLabel": "Broadcast" }, { "id": "FIZ3QaXXVF4ApScOdBx9A", "language": "curl", "code": "curl --location --request POST 'https://api.engati.ai/bot-api/v1.0/customer/61179/bot/bb67e0773bed4c7e/flow/default_fallback_msg_74963' \\\n--header 'Authorization: Basic 2082e8f4-0011-479b-9edb-74293c62d91b-GkOuZiq' \\\n--header 'Content-Type: application/json' \\\n--data-raw ''", "customLabel": "API Triggers" }, { "id": "Sje6Oda1qufYdEJy-h0y5", "language": "curl", "code": "curl --location 'https://api.engati.ai/bot-api/v2.0/customer/52075/bot/19fc4e904cbc4358/broadcast' \\\n--header 'Authorization: Basic 65560f12-2c9a-g5ac-a34r-acb596a28704-FRSayEL' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"broadcastId\": null,\n \"broadcastTitle\": \"testing broadcast\",\n \"publishedOn\": \"2021-10-08T03:29:27.170Z\",\n \"platform\": \"whatsapp\",\n \"users\": [\n {\n \"phoneNumber\": \"\",\n \"email\": \"jahnavi.suthar123@engati.com\",\n \"organization\": \"ABC\",\n \"title\": \"123\",\n \"lastName\": \"Suthar\",\n \"firstName\": \"Jahnavi 1\",\n \"userName\": \"\"\n }\n ],\n \"payload\": {\n \"type\": \"WHATSAPP_TEMPLATE\",\n \"content\": [\n {\n \"type\": \"TEMPLATE\",\n \"template\": {\n \"components\": [\n {\n \"type\": \"header\",\n \"parameters\": [\n {\n \"type\": \"image\",\n \"image\": {\n \"link\": \"\"\n }\n }\n ]\n },\n {\n \"type\": \"body\",\n \"parameters\": [\n {\n \"type\": \"text\",\n \"text\": \"1\"\n }\n ]\n },\n {\n \"type\": \"button\",\n \"index\": 0,\n \"sub_type\": \"quick_reply\",\n \"parameters\": [\n {\n \"type\": \"payload\",\n \"payload\": \"\"\n }\n ]\n }\n ],\n \"namespace\": \"d44848c7_08b0_4a15_9c53_fbe0b4gft3182\",\n \"name\": \"test_template\",\n \"language\": {\n \"code\": \"en\",\n \"policy\": \"deterministic\"\n }\n }\n }\n ]\n },\n \"status\": null\n}'", "customLabel": "Broadcast Wrapper API" } ], "selectedLanguageId": "Sje6Oda1qufYdEJy-h0y5" }, "description": "", "currentNewParameter": { "label": "Body Parameter", "value": "bodyDataParameters" }, "hasTryItOut": false, "autoGeneratedAnchorSlug": "engati-apis", "legacyHash": "G9_nL-6MU14ZW-ayUJiJe" } ``` ::: ## Users API An API to fetch users who match the value specified for the attribute. Example : To get list of users who have feedback with 1 star. List of required parameters for this API call | **Parameter** | **Description** | **Type** | | ---------------- | --------------------------------------------------- | -------- | | attribute\_name | The name of the attribute associated with the user | String | | attribute\_value | The value of the attribute associated with the user | String | ## Conversations API An API to fetch a user conversation via user id Example : To store conversation data in CRM. Parameters you can pass to filter the API response | Parameter | Description | Type | | ------------------------ | ----------------------------------------------------------------------------------------------------- | ------- | | userId \[Path parameter] | The user identifier. Retrieved from users list API | String | | start\_date \[Optional] | Start Date (UTC time in milliseconds), If blank, all records will be considered. | long | | end\_date \[Optional] | End Date (UTC time in milliseconds), If blank, the current UTC time will be considered. | long | | page\_number \[Optional] | The number of pages for which the data should be displayed. By default, the first page will be shown. | integer | | Page\_size \[Optional] | Total number of records to be shown in the API call, the default value is set to 500 | integer | ## Whatsapp Template Broadcasting For template broadcasting to bulk users on Whatsapp. **Note** : Only Templates can be sent to users as per Whatsapp Policy beyond the time limts. [ Example APIs ](https://app.archbee.com/doc/ct91vOoluPR1ulR9oGwXv/20Aa1OHoaNJKI9jWCwRyO) ::Image[]{src="https://api.archbee.com/api/optimize/FEqjvWZnyymr_PEhXLLlG/dGmC3EVXS6kuBV-01Ho_h_screenshot-2022-09-29-at-20631-am.png" size="46" width="548" height="514" position="center" showCaption="false"} ## Broadcast API **To enable and use Broadcast Wrapper API please contact support\@engati.ai. ** For all channels including Whatsapp with users within time limit. For broadcast a simple text message or interactive messages to bulk users. Example : Marketing & Advertisments, Survey and Promotion. Learn more about Broadcasts in depth via [Broadcast](https://help.engati.ai/simplified-broadcast) document. Broadcast will be published based on the time mentioned in UTC, Immediate broadcasts will be sent for expired time. Multiple Numbers in list Format `"channelUserIds": [` ` "9178921978038123","9190193486731"` ` ]` ## API Trigger To trigger automations build on Engati Platform for external usecases. Example : Sending an email to a customer who fills an external website form. Learn more about Broadcasts in depth via [API Trigger](https://help.engati.ai/api-trigger) document. **Error Scenarios** Error codes you might get while making the API call. | Error Codes | Description | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | *Error Code*: 1002,*Error Message*: INVALID\_BOT\_OR\_CUSTOMER\_ID,*Error Details*: The bot id/customer id/user id provided is invalid *Error Code*: 1003, *Error Message*: INVALID\_INPUT\_DATE\_VALUE, *Error Details*: The start\_date and end\_date values are the time in milliseconds and the end\_date should be greater than start\_date. *Error Code*: 1004, *Error Message*: INVALID\_PAGE\_NUMBER, *Error Details*: Please enter the correct page number. The page number in the API is a positive integer value starting with 1. | | 401 | Unauthorized | | 403 | Forbidden | | 500 | Server-side API failure |