VocalDocscontracts 1.65.0

Create an event filter

POST /v1/event-filters

PropertyValue
Operationcreate_event_filter
GroupEvents
Scopewebhooks:write
Route classcontrol
IdempotencyIdempotency-Key accepted: a retry with the same key replays the first answer
AuditAudited webhooks.event_filter.create (mutation)
Released in1.52.0
Phase 0 hostServed (the hosted api pins 1.65.0)

Creates an event filter at revision 1 (1.52.0). Every issue is a detail of 422 validation_failed (EventFilterIssueCode): event_filter_empty when every selecting field is empty and event_filter_value_repeated for a value named twice.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the webhooks:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/event-filters" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "name": "<name>" }'

Parameters

NameInTypeRequiredDescription
idempotency-keyheaderstringnoA client-chosen key, kept 24 hours per Organization, environment and route. A replay returns the stored response.

Request body

Content type application/json, required: EventFilterCreateRequest.

FieldTypeRequiredDescription
agent_idsarray of AgentIdnoEvents whose Call, or Agent version, belongs to one of these Agents.
environmentsarray of EnvironmentnoThe environments to match; empty matches both, as livemode stays in the envelope.
namestringyes
phone_number_idsarray of PhoneNumberIdnoEvents of Calls on one of these Phone numbers.
tagsarray of CallTagnoEvents of Calls carrying any of these tags, which a pre-call hook sets.
trace_typesarray of TraceEventTypenoThe trace types a call.trace.ready keeps; empty keeps every one.

Responses

StatusContent typeShapeError codes
201application/jsonEventFilter
400application/jsonErrorEnvelopeinvalid_request
401application/jsonErrorEnvelopeunauthenticated
403application/jsonErrorEnvelopeforbidden, org_suspended
409application/jsonErrorEnvelopeidempotency_in_progress, idempotency_key_reused
422application/jsonErrorEnvelopevalidation_failed
429application/jsonErrorEnveloperate_limited
500application/jsonErrorEnvelopeinternal_error

Fields of the 201 answer

The shape is EventFilter.

FieldTypeRequiredDescription
agent_idsarray of AgentIdyesEvents whose Call, or Agent version, belongs to one of these Agents.
created_atTimestampyes
environmentsarray of EnvironmentyesThe environments to match; empty matches both, as livemode stays in the envelope.
idEventFilterIdyes
namestringyes
object"event_filter"yes
phone_number_idsarray of PhoneNumberIdyesEvents of Calls on one of these Phone numbers.
revisionintegeryesCounts writes; returned as the ETag and required in If-Match.
tagsarray of CallTagyesEvents of Calls carrying any of these tags, which a pre-call hook sets.
trace_typesarray of TraceEventTypeyesThe trace types a call.trace.ready keeps; empty keeps every one.
updated_atTimestampyes