API services (including Short Message Service)

The API service module lets you call external services. You can add new services by configuring their service interfaces and reference existing API services in your conversation flows. A service must be unreferenced before it can be deleted. You can also directly call the Alibaba Cloud Short Message Service API and Alibaba Cloud Function Compute from API services. These can be enabled with one-click authorization.

Create a service

• Service name: Enter a custom service name. The name can be up to 20 characters long.

• Service type: Select a service type. Options include generic HTTP services, integrated Short Message Service, and Function Compute.

  • If you select HTTP service as the service type, you must configure the following parameters:

    • Invocation method settings

      • If you set the invocation method to Sync, the service generates a response and returns the result after the call is complete or times out. If you set the method to Async, the caller must access the API independently to retrieve the result or timeout information.

      • Service timeout: Set the timeout period for the service call. If a timeout occurs, the system returns a TIMEOUT message.

    • Input parameter settings

      • Service receive parameters: Set the parameters that your service needs to receive. The parameter names must match the parameter names in your API service.

    • Feature configuration

      • Service interface: Choose either the GET or POST method and enter the corresponding URL.

      • Request parameters: These parameters map to the service receive parameters. You must set the names to be identical.

    • Response parameter settings

      • Service response parameters: The API requires a result in UTF-8 encoding and string format. `result=${serviceOutput}` assigns the entire result to the `result` parameter, which can be used by modules that reference this service. If the result is a JSON string, you can use `${serviceOutput.name}` to retrieve the value of the `name` field.

    • Signature authentication

      • For more information, see the Signature Calculation Guide.

  • If you select Function Compute as the service type, you must configure the following parameters:

    Note

    This service is provided by Alibaba Cloud Function Compute. You can go to the Alibaba Cloud Function Compute console to manage your functions.

    • Service: Select Alibaba Cloud Function Compute.

    • Select Function: Specifies the function to use.

    • Input parameter settings

      • Service receive parameters: Set the parameters that your service needs to receive. The parameter names must match the parameter names in your API service.

    • Response parameter settings

      • Service response parameters: The API requires a result in UTF-8 encoding and string format. `result=${serviceOutput}` assigns the entire result to the `result` parameter, which can be used by modules that reference this service. If the result is a JSON string, you can use `${serviceOutput.name}` to retrieve the value of the `name` field.

  • If you select Short Message Service as the service type, you must configure the following parameters:

    Note

    This service is provided by Alibaba Cloud Short Message Service. SMS templates and signatures are retrieved from Alibaba Cloud Short Message Service. You can go to the Alibaba Cloud Short Message Service console to manage your SMS templates and signatures.

    • Signature: Select an SMS signature that you configured in the Short Message Service console.

    • Template: Select an SMS template that you configured in the Short Message Service console.

    • Service response parameters: Use these parameters to check whether the text message was sent successfully.

      • code: The request status code. This is a pass-through of the `Code` parameter that is returned by the `SendSms` API of Alibaba Cloud Short Message Service. For a detailed list of codes, see the API error codes in the Short Message Service documentation.

      • message: The description of the status code.

Usage example

Configure the parameters as required by your service. The system supports the HTTP protocol and both GET and POST methods.

Parameter descriptions:

• Service name: A custom name for the service that is based on its function.

• Service receive parameters: The parameters that your service needs to receive.

• Request parameters: These parameters map to the service receive parameters. The names must be identical.

• Service response parameters: The parameters that are returned by the service. In a service node, you can assign these parameters to global variables.

• Service interface: The third-party API that the service calls.

• Request type: GET

• Request URL: http://127.xx.xx.xx/smsapi

• Request parameters: The input parameters that are required by the third-party API. Use `${}` to reference the service receive parameters, such as `${city}`.

• Response parameters: The result that is returned by the service API, `${serviceOutput}`, is assigned to the service response parameter.

Best practices

Create a new service. This example uses an HTTPS API to query weather information.

Set the service receive parameter to `city`. Note that the service receive parameter name must match the parameter name that is required by the API. After you enter the request parameters, map them to the corresponding service receive parameters. Note that the request parameter name must be the same as the service receive parameter name.

Then, set the service response parameters and click OK.

After you click OK, click Debug to test the API connection.

If no issues occur during debugging, publish the service.

For more information about the actual invocation method, see the Service Node - Global Service Invocation Configuration Guide.