Groupilot Docs

Events

List events

GET
/events

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Query Parameters

status?|array<>

Filter by status (repeatable). Default: every status except archived.

Response Body

Events of the account, newest first.

application/json
  1. response
items*array<>
curl -X GET 'https://app.groupilot.com/api/v1/events'
{  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "slug": "string",      "type": "punctual",      "status": "draft",      "timezone": "string",      "recurrence": {        "days": [          "sun"        ],        "time": "string",        "timezone": "string",        "excluded_dates": [          "string"        ]      },      "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",      "smart_link": "http://example.com",      "link_fallback_url": "http://example.com",      "rotation_delay_hours": 0,      "community": {        "name_template": "string",        "description": "string",        "days_before": 1,        "overflow_switch_at": 0,        "modify_groups_policy": "anyone",        "member_add_mode": "anyone"      },      "member_webhook_configured": true,      "created_at": "2019-08-24T14:15:22Z",      "updated_at": "2019-08-24T14:15:22Z"    }  ]}

Create an event

POST
/events

Send an Idempotency-Key header to make retries safe (24 h).

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Request Body

application/json
  1. body
name*string
Length1 <= length <= 120
slug*string

Lowercase letters, digits and dashes. Ends the smart link; cannot change later.

Match^[a-z0-9]+(?:-[a-z0-9]+)*$
Length1 <= length <= 60
type*EventType
Value in"punctual""recurring"
timezone?string

IANA zone. Defaults to the account's timezone. Cannot change later.

Length1 <= length <= 64
recurrence?

Required for a recurring event; the timezone is the event's.

link_fallback_url?|
Formaturi
Lengthlength <= 2000
rotation_delay_hours?integer
Range0 <= value <= 168
community?

Response Body

Created. A recurring event gets its occurrences created by the scheduler within minutes; a punctual event needs POST /events/{id}/occurrences.

application/json
  1. response
id*string
Formatuuid
name*string
slug*string
type*EventType
Value in"punctual""recurring"
status*EventStatus

active: communities are created and messages sent. paused: nothing is sent and the smart link goes to the fallback URL (or an inactive page). archived: stopped for good. draft: not started.

Value in"draft""active""paused""archived"
timezone*string
recurrence*|

Weekly recurrence in the event's timezone.

sequence_id*|

The linked sequence, if any.

Formatuuid
smart_link*string

The one link to put in your funnel: it always redirects to the next community.

Formaturi
link_fallback_url*|
Formaturi
rotation_delay_hours*integer

Hours after the live during which the smart link still points to that occurrence.

community*
member_webhook_configured*boolean
created_at*string

ISO 8601 date-time with offset.

Formatdate-time
updated_at*string

ISO 8601 date-time with offset.

Formatdate-time
smart_link_destination*
curl -X POST 'https://app.groupilot.com/api/v1/events' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "slug": "string",  "type": "punctual"}'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "slug": "string",  "type": "punctual",  "status": "draft",  "timezone": "string",  "recurrence": {    "days": [      "sun"    ],    "time": "string",    "timezone": "string",    "excluded_dates": [      "string"    ]  },  "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",  "smart_link": "http://example.com",  "link_fallback_url": "http://example.com",  "rotation_delay_hours": 0,  "community": {    "name_template": "string",    "description": "string",    "days_before": 1,    "overflow_switch_at": 0,    "modify_groups_policy": "anyone",    "member_add_mode": "anyone"  },  "member_webhook_configured": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "smart_link_destination": {    "reason": "group",    "url": "string",    "occurrence_id": "8508ee33-23a1-4a06-ae02-1eb167405e7b",    "group_number": 0  }}

Read an event

GET
/events/{id}

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Response Body

The event with its current smart link destination.

application/json
  1. response
id*string
Formatuuid
name*string
slug*string
type*EventType
Value in"punctual""recurring"
status*EventStatus

active: communities are created and messages sent. paused: nothing is sent and the smart link goes to the fallback URL (or an inactive page). archived: stopped for good. draft: not started.

Value in"draft""active""paused""archived"
timezone*string
recurrence*|

Weekly recurrence in the event's timezone.

sequence_id*|

The linked sequence, if any.

Formatuuid
smart_link*string

The one link to put in your funnel: it always redirects to the next community.

Formaturi
link_fallback_url*|
Formaturi
rotation_delay_hours*integer

Hours after the live during which the smart link still points to that occurrence.

community*
member_webhook_configured*boolean
created_at*string

ISO 8601 date-time with offset.

Formatdate-time
updated_at*string

ISO 8601 date-time with offset.

Formatdate-time
smart_link_destination*
curl -X GET 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "slug": "string",  "type": "punctual",  "status": "draft",  "timezone": "string",  "recurrence": {    "days": [      "sun"    ],    "time": "string",    "timezone": "string",    "excluded_dates": [      "string"    ]  },  "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",  "smart_link": "http://example.com",  "link_fallback_url": "http://example.com",  "rotation_delay_hours": 0,  "community": {    "name_template": "string",    "description": "string",    "days_before": 1,    "overflow_switch_at": 0,    "modify_groups_policy": "anyone",    "member_add_mode": "anyone"  },  "member_webhook_configured": true,  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "smart_link_destination": {    "reason": "group",    "url": "string",    "occurrence_id": "8508ee33-23a1-4a06-ae02-1eb167405e7b",    "group_number": 0  }}

Change an event's settings

PATCH
/events/{id}

The slug (smart link) and the timezone cannot change; name can (the link and the existing communities keep their names, the next communities use the new one). Status changes go through pause / resume; the recurrence through recurrence; the sequence through sequence.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
name?string

Display name. The slug (smart link) and the communities that already exist keep their names; the next communities use the new one.

Length1 <= length <= 120
type?EventType
Value in"punctual""recurring"
link_fallback_url?|
Formaturi
Lengthlength <= 2000
rotation_delay_hours?integer
Range0 <= value <= 168
community?
apply_to_existing_communities?

Also rename / re-describe the communities that already exist on WhatsApp.

Response Body

Updated.

application/json
  1. response
event*
existing_communities*|null
curl -X PATCH 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
{  "event": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string",    "type": "punctual",    "status": "draft",    "timezone": "string",    "recurrence": {      "days": [        "sun"      ],      "time": "string",      "timezone": "string",      "excluded_dates": [        "string"      ]    },    "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",    "smart_link": "http://example.com",    "link_fallback_url": "http://example.com",    "rotation_delay_hours": 0,    "community": {      "name_template": "string",      "description": "string",      "days_before": 1,      "overflow_switch_at": 0,      "modify_groups_policy": "anyone",      "member_add_mode": "anyone"    },    "member_webhook_configured": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "existing_communities": {    "total": 0,    "succeeded": 0,    "failed": 0,    "skipped": 0  }}

Pause an event

POST
/events/{id}/pause

Nothing is sent and no scheduled community is created while paused (an overflow community can still open if a community fills up); the smart link goes to the fallback URL if set. Resume later; messages whose time passed during the pause are not sent.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Response Body

Paused (or already paused).

application/json
  1. response
status*string
Value in"active""paused"
changed*boolean
canceled_elapsed_jobs?integer
curl -X POST 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/pause'
{  "status": "active",  "changed": true,  "canceled_elapsed_jobs": 0}

Resume a paused event

POST
/events/{id}/resume

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Response Body

Active again.

application/json
  1. response
status*string
Value in"active""paused"
changed*boolean
canceled_elapsed_jobs?integer
curl -X POST 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/resume'
{  "status": "active",  "changed": true,  "canceled_elapsed_jobs": 0}
PUT
/events/{id}/sequence

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
sequence_id*|

null unlinks. Pending sends of future occurrences are replaced.

Formatuuid

Response Body

Linked.

application/json
  1. response
event*
created_jobs*integer
curl -X PUT 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/sequence' \  -H 'Content-Type: application/json' \  -d '{  "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f"}'
{  "event": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string",    "type": "punctual",    "status": "draft",    "timezone": "string",    "recurrence": {      "days": [        "sun"      ],      "time": "string",      "timezone": "string",      "excluded_dates": [        "string"      ]    },    "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",    "smart_link": "http://example.com",    "link_fallback_url": "http://example.com",    "rotation_delay_hours": 0,    "community": {      "name_template": "string",      "description": "string",      "days_before": 1,      "overflow_switch_at": 0,      "modify_groups_policy": "anyone",      "member_add_mode": "anyone"    },    "member_webhook_configured": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  },  "created_jobs": 0}

Change the recurrence

PUT
/events/{id}/recurrence

Occurrences that no longer match are canceled with their pending sends; new ones are created with their sends. Past occurrences are kept. Use dry_run to preview.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
recurrence*
regenerate_window_weeks?integer
Range1 <= value <= 52
Default4
dry_run?boolean
Defaultfalse

Response Body

Diff (and the event when applied).

application/json
  1. response
dry_run*boolean
idempotent*boolean
added*array<>
cancelled*array<>
kept*array<>
event?
curl -X PUT 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/recurrence' \  -H 'Content-Type: application/json' \  -d '{  "recurrence": {    "days": [      "sun"    ],    "time": "string"  }}'
{  "dry_run": true,  "idempotent": true,  "added": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "scheduled_at": "2019-08-24T14:15:22Z"    }  ],  "cancelled": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "scheduled_at": "2019-08-24T14:15:22Z"    }  ],  "kept": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "scheduled_at": "2019-08-24T14:15:22Z"    }  ],  "event": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string",    "type": "punctual",    "status": "draft",    "timezone": "string",    "recurrence": {      "days": [        "sun"      ],      "time": "string",      "timezone": "string",      "excluded_dates": [        "string"      ]    },    "sequence_id": "7cd84c09-94f4-486c-9c49-de3b9cf3f74f",    "smart_link": "http://example.com",    "link_fallback_url": "http://example.com",    "rotation_delay_hours": 0,    "community": {      "name_template": "string",      "description": "string",      "days_before": 1,      "overflow_switch_at": 0,      "modify_groups_policy": "anyone",      "member_add_mode": "anyone"    },    "member_webhook_configured": true,    "created_at": "2019-08-24T14:15:22Z",    "updated_at": "2019-08-24T14:15:22Z"  }}

Read the backup administrator settings

GET
/events/{id}/backup-admin

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Response Body

Default number, future rule, communities.

application/json
  1. response
available*boolean

False while the feature is switched off server side.

default*|null
future_rule*|null
communities*array<>
curl -X GET 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-admin'
{  "available": true,  "default": {    "target": {      "phone_masked": "string"    },    "revision": 0,    "updated_at": "2019-08-24T14:15:22Z"  },  "future_rule": {    "enabled": true,    "target": {      "phone_masked": "string"    },    "revision": 0,    "start_occurrence_id": "fc636b8e-5fb7-4adb-8f91-7b4d71b66bf6",    "starts_at": "2019-08-24T14:15:22Z"  },  "communities": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "occurrence_id": "8508ee33-23a1-4a06-ae02-1eb167405e7b",      "scheduled_at": "2019-08-24T14:15:22Z",      "name": "string",      "number": 0,      "selectable": true,      "current": {        "target": {          "phone_masked": "string"        },        "status": "string",        "verified_at": "2019-08-24T14:15:22Z"      }    }  ]}

Set the default backup administrator number

PUT
/events/{id}/backup-admin

The number is checked on WhatsApp first, so this route is limited to 6 calls per minute per account, shared with the preview. Both numbers must have each other saved as contacts, or WhatsApp may flag the addition. Nothing is applied until a preview is confirmed.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
phone_e164*string
Match^\+[1-9][0-9]{7,14}$
expected_revision?|
Range1 <= value
Defaultnull
consent_confirmed*true

You confirm the person agrees to be made administrator.

Value intrue
contact_requirements_confirmed*true

You confirm both numbers have each other saved as contacts.

Value intrue

Response Body

Saved.

application/json
  1. response
available*boolean

False while the feature is switched off server side.

default*|null
future_rule*|null
communities*array<>
curl -X PUT 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-admin' \  -H 'Content-Type: application/json' \  -d '{  "phone_e164": "string",  "consent_confirmed": true,  "contact_requirements_confirmed": true}'
{  "available": true,  "default": {    "target": {      "phone_masked": "string"    },    "revision": 0,    "updated_at": "2019-08-24T14:15:22Z"  },  "future_rule": {    "enabled": true,    "target": {      "phone_masked": "string"    },    "revision": 0,    "start_occurrence_id": "fc636b8e-5fb7-4adb-8f91-7b4d71b66bf6",    "starts_at": "2019-08-24T14:15:22Z"  },  "communities": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "occurrence_id": "8508ee33-23a1-4a06-ae02-1eb167405e7b",      "scheduled_at": "2019-08-24T14:15:22Z",      "name": "string",      "number": 0,      "selectable": true,      "current": {        "target": {          "phone_masked": "string"        },        "status": "string",        "verified_at": "2019-08-24T14:15:22Z"      }    }  ]}

Preview a backup administrator change

POST
/events/{id}/backup-admin/preview

Returns what would change, with a preview_id valid 10 minutes. Confirm it with confirm. 6 calls per minute per account, shared with PUT /events/{id}/backup-admin.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
action*string
Value in"apply""retry""stop""enable_rule""stop_rule"
community_ids?array<>

Required for apply, retry and stop. apply and retry take one community at a time until bulk protection opens (409 bulk_apply_disabled).

Itemsitems <= 250
target?

Required for apply and enable_rule.

start_occurrence_id?string

For enable_rule: first occurrence covered.

Formatuuid

Response Body

Preview.

application/json
  1. response
preview_id*string
Formatuuid
expires_at*string

ISO 8601 date-time with offset.

Formatdate-time
action*string
target*
community_count*integer
affected_count*integer
communities*array<>
curl -X POST 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-admin/preview' \  -H 'Content-Type: application/json' \  -d '{  "action": "apply"}'
{  "preview_id": "38381d54-bf0b-45bb-b5de-59c664e2cf04",  "expires_at": "2019-08-24T14:15:22Z",  "action": "string",  "target": {    "phone_masked": "string"  },  "community_count": 0,  "affected_count": 0,  "communities": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "occurrence_id": "8508ee33-23a1-4a06-ae02-1eb167405e7b",      "disposition": "string",      "status": "string"    }  ]}

Confirm a backup administrator preview

POST
/events/{id}/backup-admin/confirm

Irreversible on WhatsApp for the communities concerned. Both acknowledgements are mandatory.

Authorization

bearerAuth
headerAuthorizationBearer <token>

An API key created in Settings > Integrations (gp_live_…), or an OAuth access token.

Path Parameters

id*string
Formatuuid

Request Body

application/json
  1. body
preview_id*string
Formatuuid
consent_confirmed*true
Value intrue
contact_requirements_confirmed*true
Value intrue

Response Body

Accepted; applied by the scheduler within minutes.

application/json
  1. response
accepted*true
Value intrue
action*string
affected_count*integer
curl -X POST 'https://app.groupilot.com/api/v1/events/497f6eca-6276-4993-bfeb-53cbbbba6f08/backup-admin/confirm' \  -H 'Content-Type: application/json' \  -d '{  "preview_id": "38381d54-bf0b-45bb-b5de-59c664e2cf04",  "consent_confirmed": true,  "contact_requirements_confirmed": true}'
{  "accepted": true,  "action": "string",  "affected_count": 0}