Ações de API personalizadas

Custom API Actions let your AI chatbot call any REST API during a conversation. You can create support tickets in Jira, look up order status from your fulfillment system, query product inventory, trigger Zapier webhooks, post data to Google Sheets, or integrate with any tool that exposes a REST API. The chatbot collects the required data from the conversation, sends the HTTP request, and presents the response to the visitor - all without human intervention. Below is the full walkthrough for building, configuring, and debugging custom API actions.

How Custom API Actions Work

A custom API action uses the Call API Request action type. The flow follows this sequence:

1. The AI chatbot detects that the visitor's intent matches the action's trigger description.
2. The AI checks the conversation for any data fields defined in the action's parameters (e.g., order number, email, product name).
3. If required data is missing, the AI asks the visitor for it conversationally.
4. Once all required data is collected, Social Intents sends the configured HTTP request to your API endpoint.
5. The API processes the request and returns a response.
6. Social Intents extracts the relevant fields from the response (based on your Expected response fields configuration) and includes them in the conversation context.
7. The visitor sees the triggered response message, optionally enriched with data from the API response.

The entire process is handled by the Social Intents server - the API call is made server-side, not from the visitor's browser. This means your API credentials are never exposed to the client and you can call internal or authenticated endpoints securely.

Configuration Reference

Here is a complete reference of all fields available when configuring a Call API Request action:

Core Fields

Field	Required	Description
Action Name	Sim	Um nome descritivo como Check_Order_Status ou Create_Support_Ticket. Must be alphanumeric with underscores.
When to use	Recommended	Natural language description of when the AI should trigger this action.
Triggered response	Recommended	The message sent to the visitor when the action fires.
HTTP Method	Sim	GET, POST, PUT, or DELETE.
Endpoint URL	Sim	The full URL of the API endpoint to call.

Data Collection Fields

Field	Description
Collect data inputs	Parameters the AI needs to collect from the visitor. Each parameter has a Name, Type (Text, Number, or Date), Description, Default Value, Array flag, and Required flag.
Request JSON template	Optional JSON body for POST and PUT requests. Use {parameter_name} placeholders for dynamic values. Hidden for GET requests.

Authentication and Headers

Field	Description
Request headers	Key-value pairs sent as HTTP headers. Use for authentication (Bearer tokens, API keys), content type, and any other headers your API requires.

Response Handling

Field	Description
Expected response fields	Fields to extract from the API response. Each field has a Name and Example Value. Extracted fields are included in the chat context for the AI to reference in its responses. Leave empty to include the entire response.

Behavior Options

Field	Description
Trigger only once per session	Prevents the action from firing more than once per chat session.
Show action button in response	Displays a clickable button alongside the triggered response.
Automatically close the chat	Closes the chat session after the action runs. Optionally includes a farewell message.

Step-by-Step: Building Your First Custom API Action

This walkthrough creates an order status lookup action - one of the most common API integrations.

HTTP Methods Explained

Choose the right HTTP method based on what your API action does:

Method	Use Case	Request Body
GET	Retrieve data - order lookups, account queries, product searches, status checks	None (parameters go in the URL)
POSTAR	Create records - new tickets, new contacts, new orders, webhook triggers	JSON body with data
PUT	Update existing records - update ticket status, modify contact info	JSON body with updated data
DELETE	Remove records - cancel orders, delete subscriptions (use with caution)	Usually none

For GET requests, parameters are typically included in the endpoint URL (e.g., /orders/{order_number}). For POST and PUT requests, parameters are included in the Request JSON template as the request body.

Request JSON Template

The Request JSON template is available for POST and PUT requests. It defines the JSON body sent with the API request. Use {parameter_name} placeholders for values the AI collects from the conversation.

Simple Template

{
  "email": "{email}",
  "name": "{name}",
  "message": "{message}"
}

Nested Template

{
  "contact": {
    "email": "{email}",
    "first_name": "{first_name}",
    "last_name": "{last_name}"
  },
  "source": "live_chat",
  "priority": "normal"
}

Template with Static and Dynamic Values

{
  "fields": {
    "project": { "key": "SUPPORT" },
    "summary": "{issue_summary}",
    "description": "{issue_description}",
    "issuetype": { "name": "Bug" },
    "reporter": { "emailAddress": "{visitor_email}" }
  }
}

In this Jira example, {issue_summary}, {issue_description}e {visitor_email} are collected from the conversation. The project key, issue type, and structure are static values set in the template.

Authentication Patterns

Most APIs require authentication. Here are the common patterns and how to configure them in Social Intents:

Bearer Token

The most common pattern. Add a header with name Authorization and value Bearer YOUR_TOKEN.

Header Name	Header Value
Authorization	Bearer sk-abc123def456...

API Key in Header

Some APIs use a custom header for the API key:

Header Name	Header Value
X-API-Key	your-api-key-here

API Key in URL

Some APIs accept the key as a URL parameter. Include it directly in the endpoint URL:

https://api.example.com/orders?api_key=YOUR_KEY&order_id={order_id}

Basic Authentication

For APIs that use HTTP Basic Auth, add the Authorization header with the base64-encoded credentials:

Header Name	Header Value
Authorization	Basic dXNlcm5hbWU6cGFzc3dvcmQ=

The value after "Basic " is the base64 encoding of username:password.

Expected Response Fields

The Expected response fields configuration tells Social Intents which fields to extract from the API response and include in the conversation context. This is important for two reasons:

1. Focused context - API responses can be large. Extracting specific fields gives the AI only the relevant data, which improves response quality.
2. Structured output - The AI can reference specific field values in its response: "Your order status is Shipped with tracking number 1Z999..."

If you leave Expected response fields empty, the entire API response body is included in the conversation context. This works for small responses but can overwhelm the AI with irrelevant data for large responses.

Nested Response Fields

If the API response has nested JSON, use dot notation in the Field Name to extract nested values:

Field Name	Example Value
data.order.status	Shipped
data.order.tracking.carrier	UPS
data.order.tracking.number	1Z999AA1012345

Common Integration Examples

Create a Zendesk Ticket

• Method: POST
• URL: https://YOUR_SUBDOMAIN.zendesk.com/api/v2/tickets
• Headers: Authorization: Basic (base64 of email/token:api_token), Content-Type: application/json

{
  "ticket": {
    "subject": "{issue_subject}",
    "description": "{issue_description}",
    "requester": {
      "name": "{visitor_name}",
      "email": "{visitor_email}"
    },
    "priority": "normal",
    "tags": ["live_chat", "chatbot"]
  }
}

Trigger a Zapier Webhook

• Method: POST
• URL: https://hooks.zapier.com/hooks/catch/YOUR_HOOK_ID
• Headers: Content-Type: application/json

{
  "email": "{email}",
  "name": "{name}",
  "company": "{company}",
  "source": "chatbot",
  "message": "{visitor_question}"
}

Zapier receives this data and can route it to any connected app - CRMs, email tools, spreadsheets, project management tools, and more.

Post to Google Sheets via Apps Script

• Method: POST
• URL: Your Google Apps Script web app URL
• Headers: Content-Type: application/json

{
  "name": "{visitor_name}",
  "email": "{visitor_email}",
  "question": "{visitor_question}",
  "timestamp": "{date}"
}

Query a Product Catalog

• Method: GET
• URL: https://api.yourstore.com/products?search={product_query}
• Expected response: name, price, availability, url

The AI collects the product search term from the visitor, calls the API, and presents matching products with their prices and availability.

Debugging and Testing

Testing with a Simple Endpoint

Before connecting to your real API, test with a simple endpoint to verify the action configuration works:

1. Use a service like webhook.site or requestbin.com to create a temporary endpoint that logs incoming requests.
2. Set the temporary URL as your endpoint URL.
3. Trigger the action from your chat widget.
4. Check the webhook.site dashboard to see the exact request Social Intents sent - verify the method, headers, body, and parameter values.
5. Once verified, switch to your real API endpoint.

Common Errors and Solutions

Issue	Likely Cause	Solution
Action does not trigger	Trigger description too narrow or vague	Rewrite the When to use field with more specific intent phrases
API returns 401 Unauthorized	Missing or invalid authentication	Check Authorization header value, verify token is not expired
API returns 400 Bad Request	Malformed JSON body	Validate the Request JSON template syntax, check for missing commas or brackets
API returns 404 Not Found	Wrong endpoint URL	Verify the URL is correct, check API version, verify {parameter} placeholders are resolved
Response data not shown in chat	Expected response fields misconfigured	Verify field names match the actual JSON response keys, check for nesting
AI asks for data visitor already provided	Parameter names do not match conversation context	Use descriptive parameter descriptions so the AI can match them to information already shared

Best Practices

• Keep endpoints fast - Your API should respond within 2 seconds. Slow endpoints create delays in the chat and degrade the visitor experience.
• Use HTTPS - Always use HTTPS endpoints. Social Intents sends API calls server-side, but HTTPS protects data in transit between Social Intents and your API.
• Validate input on the API side - Do not rely solely on the chatbot to validate data. Your API should validate and sanitize all inputs it receives.
• Return clear error messages - If your API encounters an error, return a meaningful error message. Social Intents can relay error context to the visitor rather than showing a generic failure.
• Start simple - Begin with a simple GET request that retrieves data. Once you are comfortable with the basics, move to POST requests that create records and more complex integrations.
• Use expected response fields - Extracting specific fields produces better AI responses than dumping the entire API response into the conversation context.
• Rotate API keys regularly - Update API keys and tokens on a regular rotation schedule. When you rotate a key, update the header value in your Social Intents action immediately.

Perguntas frequentes

Can I call internal (non-public) APIs?

Social Intents makes API calls from its own servers, so the endpoint must be reachable from the public internet. If your API is internal, you can expose it through a reverse proxy, API gateway, or VPN tunnel that is accessible from external servers. Alternatively, use a webhook relay service that bridges your internal network and the public internet.

Is there a timeout for API calls?

Yes. Social Intents applies a timeout to API calls to prevent indefinite waiting. If your API does not respond within the timeout period, the action fails gracefully and the visitor sees the triggered response without API-enriched data. Design your endpoints to respond quickly.

Can I chain multiple API calls?

Each action makes one API call. To chain calls - for example, look up a customer, then create a ticket for that customer - use separate actions with distinct triggers. The AI can fire both actions in sequence during the same conversation. For complex multi-step workflows, consider using a Zapier or Make webhook that handles the chaining logic on the automation platform side.

What response formats are supported?

Social Intents expects JSON responses. If your API returns XML or another format, create a middleware endpoint or use an API gateway that converts the response to JSON before it reaches Social Intents.

Can I use GraphQL endpoints?

Yes. Use POST as the HTTP method, set the endpoint to your GraphQL URL, and put the GraphQL query in the Request JSON template. Include the query as a JSON string in the standard GraphQL format: {"query": "{ ... }"}.

What to Read Next

• What Are AI Actions? - Overview of all action types.
• Capturing Leads to HubSpot, Salesforce & Dynamics 365 - Pre-built CRM integration patterns.
• Showing Buttons, Links & Embedded Content - Display interactive elements alongside API results.
• Choosing the Right Action Type - Compare Call API Request against other action types.