API Call skill

The API call skill lets your agent call any external HTTP API during a conversation. Use it to look up data in your systems, trigger workflows, create records in a CRM/ERP, or anything else that's reachable over an HTTP endpoint.

When the agent decides to use the skill, Fonema sends a POST request to the URL you configured, with a JSON body built from the parameters the agent collected during the call. The endpoint's response is fed back to the agent so it can continue the conversation.

Create the skill

1. Open your agent profile → Instructions → Edit agent.
2. In the Skills panel, click + Create skill.
3. Choose API call.

Configuration

Field	Description
Skill name	A descriptive name for the skill (e.g. Appointment confirmation).
Description	Explains to the agent what the skill does and when to use it.
End point URL	The endpoint that receives the POST request.
Auth type	Optional. Bearer Token or Basic. The field below it holds the token/credential sent in the Authorization header.
Headers	Optional. Use + Add header to include custom key/value headers in the request (e.g. an API key header).
Argument	Use + Add argument to define the values the agent should collect during the call (e.g. email, orderId). Each argument is described so the model knows what to ask for and is sent in the request body.

How the request is built

When the agent triggers the skill, Fonema builds the request body by combining several sources:

1. Arguments from the model — the values the agent gathered from the caller for each parameter.
2. Extracted values — for each parameter, if it is marked as already known (for example it was passed in as an input variable when the call was created), Fonema uses that stored value instead of asking the model to invent one.
3. Customer data — Fonema always appends the caller's phone number:

{
  "...": "your parameters",
  "customer": {
    "number": "+1XXXXXXXXXX"
  }
}

Headers and authentication

The request is sent with content-type: application/json, plus:

• Any custom headers you configured.
• An Authorization header in the form {authType} {token} when an authentication type and token are set (e.g. Authorization: Bearer abc123).

Example request

POST https://your-api.example.com/lookup
content-type: application/json
authorization: Bearer abc123
x-api-key: your-custom-header-value

{
  "email": "caller@example.com",
  "orderId": "A-1024",
  "customer": {
    "number": "+34123456789"
  }
}

Handling the response

Fonema expects a JSON response. The value returned to the agent is:

• The message field of the response, if present.
• Otherwise, the full response body.

{
  "message": "Your order A-1024 ships tomorrow."
}

The agent receives this result and uses it to continue speaking with the caller naturally.

Recommendations

• Keep your endpoint fast — it runs in the middle of a live conversation.
• Return a concise message string so the agent has a clean, speakable answer.
• Reference the skill in your prompt instructions so the agent knows when to call it and which parameters to collect.
• Test the endpoint with a real call before going to production.