Introduction

Welcome to the Romulus API documentation! You can use our API key to access Romulus API endpoints.

Authentication

To authenticate and authorize every request, you must provide a standard authorization HTTP header in every API request:

In this way you can pass the correct header with each request

curl -X GET "https://api.romulus.live/v1/some_call" -H "Authorization: {{apiKey}}"

You must replace {{apiKey}} with your personal API key.

Validate authentication

To validate your authentication key you can call /me endpoint which will return related organization ID if key is valid, HTTP 401 otherwise.

HTTP Request

POST https://api.romulus.live/v1/me

curl -X GET "https://api.romulus.live/v1/me" -H "Authorization: {{apiKey}}"

It returns JSON structured like this:

{
    "organization_id": "fjjf8-fm1j8-fmqnvnu-71hf6-1vjnvq"
}

Making requests

Pagination

Pageable response:

{
  "content": [],
  "pageable": {
    "page_number": 0,
    "page_size": 20,
    "sort": [],
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "total_pages": 1,
  "total_elements": 1,
  "size": 20,
  "number": 0,
  "sort": [],
  "first": true,
  "number_of_elements": 1,
  "empty": false
}

Generally endpoints which are used to fetch resources supports pagination.

Pagination request parameters

Property	Required	Description
page	false	page number, default 0
size	false	page size, default 20

Call tasks

By call tasks we call specific configurable jobs which perform calls connecting telephony rule from your dashboard and provided telephony number. Robocall is a type of call task where the telephony rule is generally an IVR. Currently this API section allows you to fetch robocall configurations, start robocalls and configure webhook on robocall results.

List robocall configurations

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/robocalls/configurations"

It returns paginated JSON with robocall configuration object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "name" : "Robocall - IVR with WA",
  "success_criteria" : "call_answered",
  "retry_config" : {
    "strategy" : "dynamic_delay",
    "attempts" : [
      {
        "attempt" : 1,
        "delay_sec" : 0
      }
    ]
  },
  "dnd_config" : {
    "skip_for_first_attempt" : true,
    "ranges" : [
      {
        "from" : "21:00",
        "to" : "9:00"
      }
    ],
    "days" : [
      "sunday"
    ]
  },
  "created_at" : "2024-08-15T16:24:52.434665Z",
  "updated_at" : "2024-08-15T16:24:52.434694Z"
}

This endpoint allows to fetch robocall configurations previously created in your dashboard. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/call-tasks/robocalls/configurations

Response object

Property	Description
id	unique object identifier, used to start robocall tasks
name	human readable robocall name
success_criteria	criteria to consider call task as finalized
retry_config	section which describes robocall retry configuration
dnd_config	section which describes robocall DND (Do Not Disturb) configuration

Start robocall

This request starts robocall with given configuration ID and calling +39012345678

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"robocall_configuration_id": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","phone_number":"+39012345678"}'
"https://api.romulus.live/v1/call-tasks/robocalls"

It returns JSON structured like this:

{
  "robocall_configuration_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "phone_number" : "+39012345678"
}

It returns JSON call task object:

{
  "id" : 6158,
  "phone_number" : "+34697394631",
  "attempts" : 0,
  "success_criteria" : "call_answered",
  "retry_config" : {
    "strategy" : "dynamic_delay",
    "max_attempts" : 1,
    "attempts" : [
      {
        "attempt" : 1,
        "delay_sec" : 0
      }
    ]
  },
  "dnd_config" : {
    "skip_for_first_attempt" : true,
    "ranges" : [
      {
        "from" : "22:01",
        "to" : "8:59"
      }
    ],
    "days" : [
      "sunday"
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-08-26T13:49:28.823Z",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

This endpoint starts robocall task to specified phone number and using robocall configuration which ID provided in request. Generally newly created call tasks are in PENDING status with next_attempt_at execution time.

HTTP Request

POST https://api.romulus.live/v1/call-tasks/robocalls

Response object

Property	Description
id	unique call task identifier
phone_number	destination phone number
attempts	current number of attempts
success_criteria	criteria to consider call task as finalized
retry_config	section which describes robocall retry configuration
dnd_config	section which describes robocall DND (Do Not Disturb) configuration
status	call task status
next_attempt_at	next attempt execution time

Create call task webhook subscription

This request create call task webhook subscription

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"entity_type": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","entity_type":"robocall","url":"https://your.domain.com/webhook"}'
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions"

It returns JSON structured like this:

{
  "id" : "9da94929-f88f-4f9d-a5e6-3a2689b784e8",
  "entity_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "entity_type" : "robocall",
  "url" : "https://your.domain.com/webhook",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

Call task webhook body:

{
  "robocall_id" : "12347",
  "robocall_name" : "Robocall - IVR with WA",
  "robocall_configuration_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "phone_number" : "+39012345678",
  "robocall_status" : "completed",
  "attempts" : [
    {
      "duration" : 17,
      "call_status" : "answered",
      "rule_names" : [ "Office opening" ],
      "labels" : [ "Option 1" ],
      "timestamp" : "2024-08-26T13:49:28.825Z"
    }
  ]
}

This endpoint allow to create subscription to call task results webhook. It is allowed to subscribe to all robocalls or to particular ones.

HTTP Request

POST https://api.romulus.live/v1/call-tasks/webhook-subscriptions

Request object

Parameter	Required	Description
entity_id	false	robocall configuration ID if you want to receive webhooks only for particular robocall
entity_type	true	currently the value is always `robocall`
url	true	URL where you want the webhooks to be sent to

Response object

Property	Description
id	unique webhook subscription identifier
entity_id	robocall configuration ID if you want to receive webhooks only for particular robocall
entity_type	currently the value is always `robocall`
url	URL where you want the webhooks to be sent to
created_at	webhook subscription creation time
updated_at	webhook subscription last update time

List call task webhook subscriptions

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions"

It returns paginated JSON with webhook subscription object:

{
  "id" : "9da94929-f88f-4f9d-a5e6-3a2689b784e8",
  "entity_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "entity_type" : "robocall",
  "url" : "https://your.domain.com/webhook",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

This endpoint allows to fetch webhook subscriptions present in your account. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/call-tasks/webhook-subscriptions

Delete call task webhook subscription

This request will delete call task webhook subscription with ID 9da94929-f88f-4f9d-a5e6-3a2689b784e8

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions/9da94929-f88f-4f9d-a5e6-3a2689b784e8"

HTTP Request

DELETE https://api.romulus.live/v1/call-tasks/webhook-subscriptions/{webhookSubscriptionId}

Calls

Initiate outbound call

Request to initiate call to number +390101010101 with optional parameters filled

curl -L "https://api.romulus.live/v1/ai-agents/agents/{agentId}/call" \
-H "Content-Type: application/json" \
-H "Authorization: {apiKey}" \
--data-raw "{
    \"to\": \"+390101010101\",
    \"email\" : \"[email protected]\",
    \"name\" : \"John\",
    \"timezone\" : \"Europe/Rome\",
    \"campaign_id\" : \"50713898-5501-467f-b957-31e8247c1ef0\",
}"

Success response:

{
  "id": "b126584c-7744-4c5c-9e04-6e438290234b",
  "agent_id": "8c219cfa-75fa-44b4-9d96-3768af3d654b",
  "status": "INITIATED",
  "direction": "OUTBOUND",
  "origination": "+390101010101",
  "destination": "+390202020202",
  "initiated_at": "2025-04-28T20:23:44.847014624Z"
}

Failure response:

{
  "id": "06cf931a-b180-4e52-ac0c-45977e459ee8",
  "agent_id": "8c219cfa-75fa-44b4-9d96-3768af3d654b",
  "status": "FAILED",
  "direction": "OUTBOUND",
  "origination": "+390101010101",
  "destination": "invalid number",
  "error_message": "Phone number is invalid"
}

Initiates outbound call

HTTP Request

POST https://api.romulus.live/v1/ai-agents/agents/{agentId}/call

Request body

Property	Type	Description
to	string, mandatory	phone number in e164 format
email	string, optional	user's email
name	string, optional	user's name
timezone	string, optional	user's timezone
campaign_id	string, optional	unique ID of the campaign

Agents

This API section allows fetching AI agents configured in your organization.

List agents

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/ai-agents/agents/search"

It returns paginated JSON with agent objects:

{
  "id": "0a30c0bd-74fe-4712-9121-6e93046a393e",
  "license": null,
  "name": "John Doe",
  "first_message": "{{ end_call }}",
  "prompt": "Agent prompt {{ call_forwarding_a7fb }} 1",
  "max_prompt_size": 15000,
  "language": "EN",
  "default_timezone": "Europe/Rome",
  "type": "OUTBOUND",
  "status": "CONFIGURED",
  "voice_id": "11labs-Dorothy",
  "background_id": "static-noise",
  "outbound_cli": "+380936007771",
  "created_at": "2025-03-03T18:06:48.277770Z",
  "updated_at": "2025-05-19T11:38:46.625600Z"
}

This endpoint allows fetching agent data.

HTTP Request

GET https://api.romulus.live/v1/ai-agents/agents/search

Agent call tasks

This API section describes how to create a call task using AI agent.

List agent call tasks

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks"

It returns paginated JSON with an agent call task object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "agent_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "contact_phone_number" : "+1234567890",
  "contact_name" : "John Doe",
  "contact_email" : "[email protected]",
  "contact_timezone" : "Europe/Rome",
  "attempts" : 0,
  "retry_configuration" : {
    "strategy" : "DYNAMIC_DELAY",
    "attempts" : [
      {
        "attempt" : 1,
        "attempt_delay" : 3600
      },
      {
        "attempt" : 2,
        "attempt_delay" : 7200
      },
      {
        "attempt" : 3,
        "attempt_delay" : 10800
      }
    ]
  },
  "availability_configuration" : {
    "skip_for_first_attempt" : false,
    "days" : [
      {
        "day_of_week" : "MONDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "17:00"
          }
        ]
      },
      {
        "day_of_week" : "TUESDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "17:00"
          }
        ]
      }
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-03-20T14:30:00Z",
  "created_at" : "2024-03-20T10:00:00.000000Z",
  "updated_at" : "2024-03-20T10:00:00.000000Z"
}

This endpoint allows fetching call tasks of a specified agent. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks

Start agent call task

This request creates an agent call task with a given configuration

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"contact_phone_number":"+1234567890","contact_email":"[email protected]","contact_name":"John Doe","retry_configuration":{"attempts":[{"attempt":1,"delay_sec":60},{"attempt":2,"delay_sec":200}]},"availability_configuration":{"skip_for_first_attempt":true,"days":[{"day_of_week":"MONDAY","timeranges":[{"from":"9:00","to":"15:00"}]},{"day_of_week":"TUESDAY","timeranges":[{"from":"9:00","to":"15:00"},{"from":"16:00","to":"20:00"}]}]}}'
"https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks"

It returns JSON call task object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "agent_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "contact_phone_number" : "+1234567890",
  "contact_name" : "John Doe",
  "contact_email" : "[email protected]",
  "contact_timezone" : "Europe/Rome",
  "attempts" : 0,
  "retry_configuration" : {
    "strategy" : "DYNAMIC_DELAY",
    "attempts" : [
      {
        "attempt" : 1,
        "attempt_delay" : 60
      },
      {
        "attempt" : 2,
        "attempt_delay" : 200
      }
    ]
  },
  "availability_configuration" : {
    "skip_for_first_attempt" : false,
    "days" : [
      {
        "day_of_week" : "MONDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "15:00"
          }
        ]
      },
      {
        "day_of_week" : "TUESDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "15:00"
          },
          {
            "from" : "16:00",
            "to" : "20:00"
          }
        ]
      }
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-03-20T14:30:00Z",
  "created_at" : "2024-03-20T10:00:00.000000Z",
  "updated_at" : "2024-03-20T10:00:00.000000Z"
}

This endpoint starts agent call task to specified phone number and using other contact data provided in request for agent context. Generally newly created call tasks are in PENDING status with next_attempt_at execution time.

HTTP Request

POST https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks

Request object

Parameter	Required	Description
contact_phone_number	true	phone number in e164 format which will be called by an agent
contact_email	false	contact email used in agent context
contact_name	false	contact name used in agent context
retry_configuration	false	section which describes retry configuration
retry_configuration.attempts	true (if retry_configuration is present)	array of retry attempts, first attempt is not considered to be present in this array
retry_configuration.attempts.attempt	true (if retry_configuration is present)	retry attempt index, starts with 1, maximum value 5
retry_configuration.attempts.delay_sec	true (if retry_configuration is present)	delay in seconds before the next retry attempt, minimal value is 60, maximum value is 86400
availability_configuration	false	section which describes availability configuration
availability_configuration.skip_for_first_attempt	false	specifies if to apply availability configuration for first call attempt
availability_configuration.days	true (if availability_configuration is present)	array of availability configuration per day of week
availability_configuration.days.day_of_week	true (if availability_configuration is present)	day of week
availability_configuration.days.timeranges	true (if availability_configuration is present)	array of available timeranges for given day of week
availability_configuration.days.timeranges.from	true (if availability_configuration is present)	availability period start time in format HH:mm (24h format)
availability_configuration.days.timeranges.to	true (if availability_configuration is present)	availability period end time in format HH:mm (24h format)

Messenger

This API section allows to fetch WhatsApp bots configurations and send WhatsApp template messages.

List WhatsApp bots

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/messengers/whatsapp/bots"

It returns paginated JSON with WhatsApp bot objects:

{
  "id" : "4bdad4d3-469a-4633-9f03-634836532303",
  "name" : "My WA bot",
  "templates" : [
    {
      "id" : "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4",
      "name" : "My WA bot template",
      "category" : "marketing",
      "language" : "en",
      "status" : "approved",
      "components" : [
        {
          "type" : "body",
          "format" : "text",
          "text" : "Hello, {{1}}!"
        }
      ]
    }
  ]
}

This endpoint allows to fetch WhatsApp bots data including bot templates. Object structure is pretty similar to WhatsApp API models.

HTTP Request

GET https://api.romulus.live/v1/messengers/whatsapp/bots

Send WhatsApp template message

This request sends WhatsApp template message to number +39012345678

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"bot_id": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","template_id": "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4","recipient":"+39012345678","parameters":[]}'
"https://api.romulus.live/v1/messengers/whatsapp/template-message"

Sample request body with single template parameter in template body

{
  "bot_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "template_id" : "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4",
  "recipient" : "+39012345678",
  "parameters" : [
    {
      "component" : "body",
      "component_parameters" : [
        {
          "type" : "text",
          "text" : "Marco"
        }
      ]
    }
  ]
}

It returns JSON structured like this:

{
  "success" : true
}

This endpoint allows to send WhatsApp template message. Currently template parameters supported in header and body template components.

HTTP Request

POST https://api.romulus.live/v1/messengers/whatsapp/template-message

Request object

Parameter	Required	Description
bot_id	true	WhatsApp bot ID
template_id	true	WhatsApp bot template ID
parameters	false	WhatsApp bot template parameters

Webhook Subscriptions

Webhook subscription allow you to subscribe to particular event with some additional specifications.

Webhook Subscription Breakdown

Status

Status	Description
ACTIVE	Set by default on creation
DISABLED	Can be set from API, disables webhook subscription

Events

Event	Description
AGENT_CALL_COMPLETED	Sent after AI agent call is concluded
AGENT_ACTION_COMPLETED	Sent after AI agent action is executed

Some events can be customized deeper with entity and specifications settings

Entities

Entity can customize webhooks to subscribe to a specific main subject of the Event

Entity	Description	Supported by Event
AGENT	Allows to subscribe to webhooks for specific agent	AGENT_CALL_COMPLETED, AGENT_ACTION_COMPLETED

Specifications

Specifications allow further customization for webhooks

Specification	Description	Supported by Event
ACTION_ID	Allows to subscribe to specific action by ID	AGENT_ACTION_COMPLETED
ACTION_TYPE	Allows to subscribe to specific action type	AGENT_ACTION_COMPLETED

Webhook Subscription Properties

Property	Type	Description
id	string	unique ID of the webhook subscription
event	Event	event type for webhook subscription
status	Status	current status of subscription
entity_type	Entity	type of entity for customization
entity_id	string	unique ID of entity for customization
url	string	URL that will be used as a target to send webhooks
attempts	number	amount of attempts before giving up
attempts_interval_seconds	number	interval between attempts in seconds
specifications	map, Specification to string	specifications for additional customization

List all Webhook Subscriptions

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/webhook-subscriptions/search"

Response:

{
  "content" : [
    {
      "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
      "status" : "ACTIVE",
      "event" : "AGENT_CALL_COMPLETED",
      "entity_id" : "5128437e-c64e-44e2-8f37-c8ef05530a2b",
      "entity_type" : "AGENT",
      "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
      "attempts" : 3,
      "attempts_interval_seconds" : 10,
      "specifications" : { },
      "created_at" : "2025-04-17T07:59:35.813396Z",
      "updated_at" : "2025-04-17T07:59:35.813444Z"
    },
    {
      "id" : "1737134378f14367961a35932f440d1f",
      "status" : "ACTIVE",
      "event" : "AGENT_ACTION_COMPLETED",
      "entity_id" : null,
      "entity_type" : null,
      "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
      "attempts" : 3,
      "attempts_interval_seconds" : 10,
      "specifications" : {
        "ACTION_TYPE" : "CALL_FORWARDING"
      },
      "created_at" : "2025-04-17T08:47:37.322850Z",
      "updated_at" : "2025-04-17T08:47:37.322862Z"
    }
  ],
  "pageable" : {
    "page_number" : 0,
    "page_size" : 20,
    "sort" : [ ],
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "total_pages" : 1,
  "total_elements" : 5,
  "last" : true,
  "size" : 20,
  "number" : 0,
  "sort" : [ ],
  "number_of_elements" : 5,
  "first" : true,
  "empty" : false
}

Returns all Webhook Subscriptions on account

HTTP Request

GET https://api.romulus.live/v1/webhook-subscriptions/search

Get Webhook Subscription

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
"https://api.romulus.live/v1/webhook-subscriptions/143f5506b2a14c8ea3a565d7d1f40c51"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "ACTIVE",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : null,
  "entity_type" : null,
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : { },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Retrieves a single Webhook Subscription by ID

HTTP Request

GET https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions/{webhookSubscriptionId}

Create Webhook Subscription

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
-d '{ "event": "AGENT_ACTION_COMPLETED", "url": "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7", "attempts": 3, "entity_id": "5128437e-c64e-44e2-8f37-c8ef05530a2b", "entity_type": "AGENT", "specifications": { "ACTION_TYPE": "CALL_FORWARDING" }, "attempts_interval_seconds": 10 }'
"https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "ACTIVE",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : "AGENT",
  "entity_type" : "5128437e-c64e-44e2-8f37-c8ef05530a2b",
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : { 
    "ACTION_TYPE" : "CALL_FORWARDING"
  },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Creates Webhook Subscription

HTTP Request

POST https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions

Request body

Property	Type	Mandatory
event	Event	true
entity_type	Entity	false
entity_id	string	true if entity_type set, otherwise false
url	string	true
attempts	number	false, defaults to 3
attempts_interval_seconds	number	false, defaults to 10
specifications	map, Specification to string	false

Update Webhook Subscription

curl -X PUT -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
-d '{ "status": "DISABLED", "url": "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7", "attempts": 3, "entity_id": "5128437e-c64e-44e2-8f37-c8ef05530a2b", "entity_type": "AGENT", "specifications": { "ACTION_TYPE": "CALL_FORWARDING" }, "attempts_interval_seconds": 10 }'
"https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "DISABLED",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : null,
  "entity_type" : null,
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : {
    "ACTION_TYPE" : "CALL_FORWARDING"
  },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Updates Webhook Subscription by ID

HTTP Request

PUT https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions/{webhookSubscriptionId}

Request body

Property	Type	Mandatory
status	Status	true
entity_type	Entity	false
entity_id	string	true if entity_type set, otherwise false
url	string	true
attempts	number	false, defaults to 3
attempts_interval_seconds	number	false, defaults to 10
specifications	map, Specification to string	false

Delete Webhook Subscription

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
"https://api.romulus.live/v1/webhook-subscriptions/143f5506b2a14c8ea3a565d7d1f40c51"

Deletes Webhook Subscription by ID

HTTP Request

DELETE https://api.romulus.live/v1/webhook-subscriptions/webhook-subscriptions/{webhookSubscriptionId}

Webhook Event Models

Call completed (AGENT_CALL_COMPLETED)

Example:

 {
  "event" : "AGENT_CALL_COMPLETED",
  "call_id" : "b4d8cb59-a2c0-4424-9201-5e36981c2223",
  "agent_id" : "950c3899-d6b2-45d9-b8df-724a6c614c5e",
  "status" : "COMPLETED",
  "direction" : "OUTBOUND",
  "origination" : "+39----------",
  "destination" : "+39----------",
  "duration" : 70,
  "call_recording_url" : "https://romulus-ai-agent.s3.eu-north-1.amazonaws.com/prod/call-recordings/0a39ebe0---------/b0------------.mp3",
  "transcriptions" : [
    {
      "speaker" : "USER",
      "text" : "Hello."
    },
    {
      "speaker" : "AGENT",
      "text" : "Hello, I'm Maya from Tasty Cakes. How can I help you?"
    }
  ],
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "summary" : "The caller contacted Tasty Cakes to make a table reservation for the following day. After checking availability, Maya from Tasty Cakes confirmed a reservation for 5:00 PM and wished the caller a wonderful day.",
  "action_results" : [
    {
      "type" : "CALL_FORWARDING",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "attempts" : [
          {
            "target" : "39-------",
            "child_call_id" : "05647ef8-50cb-4fa7-93c0-83ce3eddb45c",
            "status" : "INITIATED"
          }
        ]
      }
    },
    {
      "type" : "WHATS_APP_MESSAGE",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "send_message_result_logs" : [
          {
            "extracted_properties" : [
              {
                "key" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
                "value" : "Si"
              }
            ],
            "phone_number" : "+39...",
            "success" : true,
            "attempted_at" : "2025-03-31T10:18:47Z",
            "message_components" : [
              {
                "type" : "header",
                "format" : "text",
                "text" : "Grazie per aver visitato il nostro stand Voxloud!"
              },
              {
                "type" : "body",
                "text" : "Siamo entusiasti di aver avuto l'opportunità di conoscerti durante l'evento e di condividere con te come il nostro servizio Voxloud può portare valore alla tua attività.\uD83D\uDE4C\nPer approfondire e discutere delle tue esigenze, clicca sul pulsante qui sotto \"DEMO\" e fissa un appuntamento con uno dei nostri specialisti.\uD83D\uDCC5\nNon vediamo l'ora di sentirti!\uD83D\uDE0A"
              },
              {
                "type" : "footer",
                "text" : "Some text"
              },
              {
                "type" : "buttons",
                "buttons" : [
                  {
                    "type" : "url",
                    "text" : "DEMO",
                    "url" : "https://..."
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    {
      "type" : "APPOINTMENT",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "appointment_entries" : [
          {
            "step" : "AVAILABILITY",
            "success" : true,
            "attempted_at" : "2025-03-28T12:33:24Z"
          },
          {
            "step" : "SCHEDULING",
            "success" : true,
            "attempted_at" : "2025-03-28T12:33:24Z",
            "event_data" : {
              "id" : "event_id",
              "url" : "https://...",
              "start" : {
                "date" : "2025-03-31",
                "time" : "15:00"
              },
              "end" : {
                "date" : "2025-03-31",
                "time" : "16:00"
              },
              "timezone" : "Europe/Rome"
            }
          }
        ]
      }
    },
    {
      "type" : "DATA_EXTRACTION",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "extracted_properties" : [
          {
            "description" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
            "value" : "Si"
          }
        ]
      }
    }
  ],
  "ended_at" : "2025-03-31T10:18:47Z",
  "initiated_at" : "2025-03-31T10:17:36.696603Z"
}

Call Event properties

Property	Type	Description
event	string, [AGENT_CALL_COMPLETED]	event type for webhook subscription, always AGENT_CALL_COMPLETED
call_id	string	unique ID of the call
agent_id	string	unique ID of the agent
status	string	final status of the call
direction	string, [INBOUND, OUTBOUND]	call direction
origination	string	phone number in e164 format of the caller
destination	string	phone number in e164 format of the callee
duration	number	call duration in seconds
call_recording_url	number	call recording URL
transcriptions	array, Transcription	call transcription
summary	string	summary of the call generated by AI
metadata	Metadata	call metadata
action_results	array, ActionResult	specifications for additional customization
initiated_at	string	date time of the moment call was initiated (not started)
ended_at	string	date time of the moment call was ended

Metadata properties

Property	Type	Description
contact_data	ContactData	metadata of the contact, set before the call started

ContactData properties

Property	Type	Description
email	string	email of the contact
name	string	name of the contact
timezone	string	timezone of the contact
phone_number	string	phone number of the contact in e164 format

Transcription properties

Property	Type	Description
speaker	string, [USER, AGENT]	speaker, can be AI or user who speaks with it
text	string	speech of the speaker

ActionResult

Property	Type	Description
type	string, [APPOINTMENT, CALL_FORWARDING, DATA_EXTRACTION, WHATS_APP_MESSAGE]	action type
action_id	string	unique ID of the action
data	DataExtractionResult, WhatsAppMessageResult, CallForwardingResult, AppointmentResult	result of the action, based on action type

DataExtractionResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation

ExtractedProperty:

Property	Type	Description
description	string	description of the property, set during action creation
value	string	value, set by AI during conversation

WhatsAppMessageResult properties:

Property	Type	Description
send_message_result_logs	array, SendMessageResult	result of send WA message attempt

SendMessageResult:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation
phone_number	string	phone number in e164 format, that was used as a target for WA message
success	boolean	indicates if attempt was successful or not
attempted_at	string	date time of the moment send WA message attempt happened
message_components	array, MessageComponent	components of WA message

CallForwardingResult properties:

Property	Type	Description
attempts	array, CallForwardingAttempt	array of call forwarding attempts

CallForwardingAttempt:

Property	Type	Description
target	string	call forwarding target phone number
child_call_id	string	unique ID of the call created during forwarding
status	string [INITIATED, FAILED]	status of the attempt

AppointmentResult properties:

Property	Type	Description
appointment_entries	string, AppointmentEntry	list of appointment related actions

AppointmentEntry:

Property	Type	Description
step	string, [AVAILABILITY, SCHEDULING]	appointment step
success	boolean	indicates if step was executed successfully
attempted_at	string	date time of the moment step was attempted
event_data	EventData	data of the created event

EventData:

Property	Type	Description
id	string	external event id
url	string	event URL
start	DateTime	date time of the event start
end	DateTime	date time of the event end
timezone	string	timezone of the start and end time (calendar timezone)

DateTime:

Property	Type	Description
date	string	YYYY-MM-DD
time	string	HH:MM

Action completed (AGENT_ACTION_COMPLETED)

Call Forwarding action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "CALL_FORWARDING",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "target" : "+39--------",
    "child_call_id" : "b3fa49d6-863c-49bd-8774-f65f80dad02b",
    "status" : "INITIATED"
  }
}

Data Extraction action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "DATA_EXTRACTION",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "extracted_properties" : [
      {
        "description" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
        "value" : "Si"
      }
    ]
  }
}

WhatsApp Message action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "WHATS_APP_MESSAGE",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "extracted_properties" : [
      {
        "key" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
        "value" : "Si"
      }
    ],
    "phone_number" : "+39...",
    "success" : true,
    "attempted_at" : "2025-03-31T10:18:47Z",
    "message_components" : [
      {
        "type" : "header",
        "format" : "text",
        "text" : "Grazie per aver visitato il nostro stand Voxloud!"
      },
      {
        "type" : "body",
        "text" : "Siamo entusiasti di aver avuto l'opportunità di conoscerti durante l'evento e di condividere con te come il nostro servizio Voxloud può portare valore alla tua attività.\uD83D\uDE4C\nPer approfondire e discutere delle tue esigenze, clicca sul pulsante qui sotto \"DEMO\" e fissa un appuntamento con uno dei nostri specialisti.\uD83D\uDCC5\nNon vediamo l'ora di sentirti!\uD83D\uDE0A"
      },
      {
        "type" : "footer",
        "text" : "Some text"
      },
      {
        "type" : "buttons",
        "buttons" : [
          {
            "type" : "url",
            "text" : "DEMO",
            "url" : "https://..."
          }
        ]
      }
    ]
  }
}

Appointment action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "APPOINTMENT",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "step" : "SCHEDULING",
    "success" : true,
    "attempted_at" : "2025-03-28T12:33:24Z",
    "event_data" : {
      "id" : "event_id",
      "url" : "https://...",
      "start" : {
        "date" : "2025-03-31",
        "time" : "15:00"
      },
      "end" : {
        "date" : "2025-03-31",
        "time" : "16:00"
      },
      "timezone" : "Europe/Rome"
    }
  }
}

Action event properties:

Property	Type	Description
event	string, [AGENT_ACTION_COMPLETED]	event type, always AGENT_ACTION_COMPLETED
action_type	string, [APPOINTMENT, CALL_FORWARDING, DATA_EXTRACTION, WHATS_APP_MESSAGE]	action type
action_id	string	unique ID of the action
call_id	string	unique ID of the call
agent_id	string	unique ID of the agent
metadata	Metadata	call metadata
data	DataExtractionResult, WhatsAppMessageResult, CallForwardingResult, AppointmentResult	result of the action, based on action type

Metadata properties:

Property	Type	Description
contact_data	ContactData	metadata of the contact, set before the call started

ContactData properties:

Property	Type	Description
email	string	email of the contact
name	string	name of the contact
timezone	string	timezone of the contact
phone_number	string	phone number of the contact in e164 format

Action specific data

DataExtractionResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation

ExtractedProperty:

Property	Type	Description
description	string	description of the property, set during action creation
value	string	value, set by AI during conversation

WhatsAppMessageResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation
phone_number	string	phone number in e164 format, that was used as a target for WA message
success	boolean	indicates if attempt was successful or not
attempted_at	string	date time of the moment send WA message attempt happened
message_components	array, MessageComponent	components of WA message

CallForwardingResult properties:

Property	Type	Description
target	string	call forwarding target phone number
child_call_id	string	unique ID of the call created during forwarding
status	string [INITIATED, FAILED]	status of the attempt

AppointmentResult properties:

Property	Type	Description
step	string, [SCHEDULING]	appointment step, always SCHEDULING
success	boolean	indicates if step was executed successfully
attempted_at	string	date time of the moment step was attempted
event_data	EventData	data of the created event

EventData:

Property	Type	Description
id	string	external event id
url	string	event URL
start	DateTime	date time of the event start
end	DateTime	date time of the event end
timezone	string	timezone of the start and end time (calendar timezone)

DateTime:

Property	Type	Description
date	string	YYYY-MM-DD
time	string	HH:MM

Errors

The Romulus API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is not well-formed.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested resource is not accessible with your credentials.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
429	Too Many Requests -- You're doing too many requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.