Campaigns

Campaigns are where you communicate with the community in an event-driven way in Our Voice - they are a set of groups that you address at the same time. On this page, we'll dive into the different campaign endpoints you can use to manage campaigns programmatically. We'll look at how to query, create, update and delete campaigns.

The campaign template contains all the information about the campaigns that grouped the group, including how your campaigns reacted to them.

Properties

Name
id
Type
string
Description
Unique identifier for the campaign.
Name
name
Type
string
Description
The name of the campaign.
Name
type
Type
string
Description
The type of the campaign.
Name
repeat
Type
enum
Description
The repeat of the campaign. Types of repeat : never, daily, weekly, monthly, yearly.
Name
status
Type
enum
Description
The status of the campaign. Types of status : scheduled, ongoing, sent, failed, canceled, active, ended.
Name
start_time
Type
datetime
Description
The start time of the campaign.
Name
end_time
Type
datetime
Description
The end time of the campaign.
Name
group_id
Type
string
Description
Unique identifier for the group the campaign belongs to.
Name
account_id
Type
string
Description
Unique identifier for the account the campaign belongs to.
Name
created_at
Type
timestamp
Description
Timestamp of when the sms was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the sms was updated.

GET/v1/campaigns

Retrieve Campaign

This endpoint allows you to retrieve the campaign in Ourvoice.

Request

GET

/v1/campaigns

curl --request GET \
  --get "https://api.getourvoice.com/v1/campaigns?page=1&limit=10&filter[to]=&filter[from]=&filter[direction]=outgoing&filter[status]=completed&filter[duration]=" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

Response (200)

{
  "data": [
    {
      "id": "1498e4ff-3d09-4dba-bb7c-62851729f7ea",
        "type": "sms",
        "voices": null,
        "messages": [],
        "name": "My first campaign",
        "repeat": "daily",
        "start_date": "2023-05-31T14:37:56.976622Z",
        "end_date": "2023-06-01T14:37:56.976630Z",
        "status": "sent",
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    },
    {
        "id": "184f2fe6-7f3c-4350-b197-a659f3ba8cfa",
        "type": "sms",
        "voices": null,
        "messages": [],
        "name": "My first campaign",
        "repeat": "daily",
        "start_date": "2023-05-31T14:37:56.979661Z",
        "end_date": "2023-06-01T14:37:56.979666Z",
        "status": "sent",
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    }
  ]
}

POST/v1/campaigns

Store a newly campaign

This endpoint allows you to store a newly campaign in Ourvoice.

Required attributes

Name
name
Type
string
Description
The name of the campaign.
Name
type
Type
string
Description
The type of the campaign.
Name
audio_url
Type
string
Description
The URL for the audio file.
Name
sender_id
Type
string
Description
The id of the sender. Your use sender_id or sender_name. Not both.
Name
sender_name
Type
string
Description
The name of the sender. Your use sender_name or sender_id. Not both.
Name
group_ids
Type
string[]
Description
The group id.
Name
repeat
Type
string
Description
The repeat of the campaign. See the list at the top of this page for possible repeat values.
Name
start_date
Type
string
Description
Date in the format Y-m-d H:i:s of when the campaign starts.
Name
end_date
Type
string
Description
Date in the format Y-m-d H:i:s of when the campaign will end.

Request

POST

/v1/campaigns

curl --request POST \
  "/v1/campaigns" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --data "{
    \"name\": \"NawiAgodjie",
    \"type\": \"distinctio\",
    \"group_ids\": [\"aa143351-379b\"],
    \"repeat\": \"architecto\",
    \"start_date\": \"2024-05-30\",
    \"end_date\": \"2024-10-19\"
}"

Response (200)

{
  "data": {
   "id": "aa5c674c-780d-45e1-90c0-ee0dc2124e4d",
    "type": "sms",
    "voices": null,
    "messages": [],
    "name": "My first campaign",
    "repeat": "daily",
    "start_date": "2023-05-31T14:37:56.987813Z",
    "end_date": "2023-06-01T14:37:56.987820Z",
    "status": "sent",
    "created_at": "2023-05-31T14:37:56.000000Z",
    "updated_at": "2023-05-31T14:37:56.000000Z"
  }
}

GET/v1/campaigns/{id}

Display a specific campaign.

This endpoint allows you to display the specific campaign in Ourvoice.

Required attributes

Name
id
Type
string
Description
The ID of the campaign.

Request

GET

/v1/campaigns/{id}

curl --request GET \
  --get "https://api.getourvoice.com/v1/campaigns/07c4cd34-ca10-4c64-9c6c-21fb6f1ebe0d" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"

PUT/v1/campaigns/{id}

Update a specific campaign

This endpoint allows you to update the specific campaign in Ourvoice. It also takes a PATCH as a method.

Required attributes

Name
id
Type
string
Description
The ID of the campaign.

Request

PUT

/v1/campaigns/{id}

curl --request PUT \
  "/v1/campaigns/ac3089da-91cf-4c5a-bf4d-6afa590077d1" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \

DELETE/v1/campaigns/{id}

Delete a specific campaign

This endpoint allows you to remove the specific campaign in Ourvoice.

Required attributes

Name
id
Type
string
Description
The ID (uuid) of the campaign.

Request

DELETE

/v1/campaigns/{id}

curl --request DELETE \
  "/v1/campaign/WAz8eIbvDR60rouK" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"