Outbound Phone Calling API (Legacy) - AI Assistant

Pre-requisites

Plus Plan subscription

To access this API, please contact your account manager to request an API key. This API uses a support-issued key (you can’t generate one yourself like you can for our other APIs).

Overview

The Outbound Call API allows you to trigger an outbound call from your system to a specified phone number. The call can be customized with specific prompts, questions, and rules, and can include metadata about the customer. This API is useful for any situation where automated outbound calls are required.

Endpoint

POST https://phone.mylibby.ai/outbound

Request Payload

The request payload should be a JSON object that looks like the following

Option 1: provide introNotes that will allow AI to generate the intro and voicemail messages.

{
  "name": "Chris",
  "introNotes": "We are an event planning company, Check and see if they are interested in event planning services",
  "toPhoneNumber": "+1xxxxxxxxxx",
  "fromPhoneNumber": "+1xxxxxxxxxx",
  "formInfo": [
    {"Have you had an event planner before?":"Yes"},
    {"What's your budget?": "100 per month"}
  ]
}

Option 2: provide the explicit introMessage and introVoicemail

{
  "name": "Chris",
  "introMessage": "Hi, we see that you expressed interest in our services. Can I answer any questions or schedule a demo with you?",
  "introVoicemail": "Hi, we're calling you back as we see you've expressed interest in our services. Call us back to help answer questions.",
  "toPhoneNumber": "+1xxxxxxxxxx",
  "fromPhoneNumber": "+1xxxxxxxxxx",
  "formInfo": [
    {"Have you had a photographer before?":"Yes"},
    {"What's your budget?": "100 per month"}
  ]
}

Parameters

name (string): The name of the person being called. This is used to personalize the conversation.
toPhoneNumber (string): The phone number to call. This should be in E.164 format (e.g., “+1505XXXXXXX”).
fromPhoneNumber (string): The agent’s phone number initiating the call. This should also be in E.164 format (e.g., “+1XXXXXXX”).
introNotes (string, optional): This is used to generate the introductory message or voicemail content. This will be used to start the conversation or leave a message if the recipient doesn’t answer. It will not match the message, but rather be used in generating the message(s)
introMessage (string, optional): Use this instead of introNotes if you want to define exactly how you want the assistant to say after the user answers the phone. If you define this, you must provide an introVoicemail as well.
introVoicemail (string, optional): Use this instead of introNotes if you want to define exactly the voicemail you want the assistant to leave if the user does not answer the phone.
formInfo (array of objects): Metadata about the customer. This can include any relevant information that should be referenced during the call. Each object represents a key-value pair. Usually this information is taken in and dynamically set from a form.

Response

200 - Call has been processed

{
    "message": "Outbound call processed"
}

Common Error Responses

403 - Forbidden Typically this indicates you did not add a token or the token is expired.

{
    "message": "Forbidden: Incorrect scopes"
}

404 - Not Found There is no agent for the outgoing number.

{
    "message": "Agent not found for this number"
}

Authentication

Overview

The Cognito Token API is used to obtain an access token from Amazon Cognito by making a POST request to the OAuth2 token endpoint. This token can be used to authenticate requests to the Outbound API.

Endpoint

POST https://libby.auth.us-east-1.amazoncognito.com/oauth2/token

Request

Headers

Content-Type: application/x-www-form-urlencoded Specifies that the request body is URL-encoded.
Optional Cookie: XSRF-TOKEN={} The CSRF token for protecting against cross-site request forgery.

Body

The body of the request should be URL-encoded and include the following parameters:

grant_type (string): The type of grant being requested. For client credentials, use client_credentials.
client_id (string): The client ID for your application. This identifies your app to the authentication server.
client_secret (string): The client secret associated with the client ID. This is used to authenticate your app.
scope (string): The scope of the access being requested. This should be the resource server scope, e.g., external-api-resource-server-1/call.out.

Example Request

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Cookie", "XSRF-TOKEN=0d12bcfe-f40f-4182-8c00-aa344553747f");

const urlencoded = new URLSearchParams();
urlencoded.append("grant_type", "client_credentials");
urlencoded.append("client_id", "your-client-id");
urlencoded.append("client_secret", "your-client-secret");
urlencoded.append("scope", "external-api-resource-server-1/call.out");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("https://libby.auth.us-east-1.amazoncognito.com/oauth2/token", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response

The response will contain an access token if the request is successful.

{
  "access_token": "eyJraWQiOiJLT...",
  "token_type": "Bearer",
  "expires_in": 3600
}

access_token (string): The token that can be used to authenticate requests to other services.
token_type (string): The type of token returned, typically Bearer.
expires_in (integer): The number of seconds until the token expires.
scope (string): The scope of access granted by the token.

Error Response

If the request fails, the response will include an error message and error code.

400 - Bad Request Likely a bad client_id or client_secret.

{
    "error": "invalid_client"
}

Notes

CSRF Protection: The Cookie header includes a CSRF token to protect against cross-site request forgery. Ensure that this token is valid and properly handled in your application.
Token Storage: Store the access_token securely and avoid exposing it to unauthorized parties.