Basic Requirements for Developing a Technical Integration

Through an integration, you can connect the Virtual Assistant to another external service.

To proceed with the integration, you’ll need to provide all the required information about the service you want to integrate with. This could be your own service or a third-party service. Make sure all information is current at the time of development.

This includes technical documentation, access credentials, methodologies, protocols, security requirements, and any other details necessary for implementation.

 The general steps to follow once you’ve informed us which service you need to integrate are:

1. We’ll send you the specific requirements needed to carry out the integration.
2. You’ll need to share these requirements with your technical team or with the service provider involved.
3. Once the information has been gathered, you must send us the requested documentation and data for analysis.
4. Following the corresponding validation, we will proceed with the implementation and execution of the integration.

 This information will allow us to assess the feasibility of the integration and define the necessary steps to move forward.

Types of Integration and Their Requirements 

➡️ Web Service Integrations

Web service integrations allow you to share information with other systems and exchange data without needing to know the details of their respective information systems.

 Learn more: What is a Web Service?  

You can integrate with any type of web service, regardless of the data transmission and reception technology you use (REST or SOAP). 

1. Implementation time: Developing a web service takes, on average, one week. The timeframe may be extended depending on the complexity of each case, for example, if it requires authentication methods or VPN configuration. 
2. Usage modes in Virtual Assistant: 
   1. Proactive: As soon as the user starts a conversation, the assistant offers a list of available options. The user doesn’t need to make a specific query for it to be triggered.
   2. On-demand: The user triggers the integration by asking a question.

 Integrations with third-party APIs

Virtual Assistant supports any type of integration with third-party APIs. Documentation should preferably be provided in Postman, with sufficient details and examples. You can see an example here: API Documentation. 

 Below, we’ll explain what information we need to develop an integration using Aivo Engageware.

1. The question that will trigger the integration. 
2. The routes, endpoints, or services that will be used to respond. 
   1. Third-party service data: Each service to be queried must be associated with an endpoint and include:
      1. Input parameters. 
      2. Output parameters. 
      3. Description of each parameter. 
      4. Send and receive format. 
      5. An endpoint that consumes the service and the header parameters or methods to be used. 
   2. The documentation can be presented in any of the following formats, which list the possible API options: 
      1. Postman Collection (recommended) 
      2. Swagger 
      3. Apiary 
      4. RAML 
3. Possible scenarios: It is important to document each scenario the user will go through. We recommend using flowcharts that show the step-by-step process, including all possible cases, their responses, and the endpoints accessed at each stage. 
4. The data we need to use from Aivo Engageware in each scenario to perform the tests. 
   1. An example of each endpoint as a curl command. 
   2. The expected response from each service in all cases. 
   3. All possible error messages the service may return, with an explanation and a possible solution for each one. 
   4. Test cases and parameters that allow us to verify all possible scenarios. 

 Additional information: To avoid delays in development, we also need to know: 

1. Data types and formats to be sent and received: JSON, arrays, XML.
2. Network security: If you have any level of network security in place, it will be necessary to whitelist IP addresses and set up VPNs. 
3. Testing environment: Do you have a testing environment? Is it stable? In the event of an outage, how long is the estimated recovery time? 
4. Authentication: If the services require authentication, please specify: 
   1. The type of authentication to be used. 
   2. The credentials for the available environments.

 Factors to consider: 

1. In some cases, third-party services require specific configurations to allow access by the Virtual Assistant. 
2. Each provider must keep their services active and ensure access is available at the time of testing. 
3. Documentation cannot be submitted in Excel format. 

Examples of documentation to be submitted

Endpoints by service via Swagger: The documentation must be organized by workflow. For each workflow, it must include all service endpoints with: the data to be sent and received, the purpose and function of each service, the data types sent and received, and what each is used for.

1. Swagger allows you to specify the request method and the endpoint’s suffix.

2. Notes on what the service will receive.

3. The response that should be received from the service.

4. The JSON to be sent or the format for sending it.

5. The type of parameters to send if you want to load them rather than pass them via a structure.

6. The various messages that will be received: Curl, endpoint, response body, etc.

7. Swagger allows you to run tests directly, either by entering data or through the sent JSON.

8. Finally, a flowchart is provided as an example, showing the appointment cancellation process from start to finish, including each possible scenario, decision-making steps, and services to be consulted at each stage. This provides a comprehensive overview of the procedure and the validations to be performed for all teams involved.