Campaign

Overview

The VoIPBIN campaign API offers a comprehensive campaign service designed for massive outbound calling, including SMS, email, and SNS (Social Networking Service) messaging. These outbound campaigns are tailored to efficiently reach a large number of recipients for various purposes such as telemarketing, telesales, collections, and notifications.

_images/campaign_overview_overview.png

Resource

The VoIPBIN’s campaign is composed of several essential resources that contribute to its effectiveness and functionality.

_images/campaign_overview_resource.png

  • Queue: Represents the waiting place for calls and groups of agents who handle the calls.

  • Outdial: Contains the list of target destinations to which the campaign will reach out.

  • Outplan: Specifies the dialing strategy, determining how and when the calls will be initiated.

5W1H

The campaign adheres to the 5W1H principle, which focuses on answering specific questions for each resource:

  • Campaign: Defines the purpose of making calls and outlines the actions to be taken after a call is established (Why/What).

  • Queue (Agents): Identifies the agents or recipients who will receive the call after it is answered (Who).

  • Outdial: Specifies the destinations or recipients to whom the calls will be made (Where).

  • Outplan: Determines the approach and timing for making the calls (How/When).

Dialing strategy

Effectively reaching out to customers is of utmost importance, and VoIPBIN provides multiple retry options to ensure successful communication.

_images/campaign_overview_dialing_strategy.png

By employing these dialing strategies, the campaign enhances the chances of successfully connecting with recipients, optimizing outreach efforts, and ensuring effective communication with the target audience.

Campaign

Campaign

{
    "id": "<string>",
    "type": "<string>",
    "name": "<string>",
    "detail": "<string>",
    "status": "<string>",
    "service_level": <number>,
    "end_handle": "<string>",
    "actions": [
        ...
    ],
    "outplan_id": "<string>",
    "outdial_id": "<string>",
    "queue_id": "<string>",
    "next_campaign_id": "<string>",
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

  • id: Campaign’s ID.

  • type: Campaign’s type. See detail here.

  • name: Campaign’s name.

  • detail: Campaign’s detail.

  • status: Campaign’s status. See detail here.

  • service_level: Campaign’s service level. See detail here.

  • end_handle: Campaign’s outdial list end handle. See detail here.

  • actions: Campaign’s list of actions. See detail here.

  • outplan_id: Outplan’s ID.

  • outdial_id: Outdial’s ID.

  • queue_id: Queue’s ID.

  • next_campaign_id: Next campaign’s ID.

Example

{
    "id": "183c0d5c-691e-42f3-af2b-9bffc2740f83",
    "type": "call",
    "name": "test campaign",
    "detail": "test campaign detail",
    "status": "stop",
    "service_level": 100,
    "end_handle": "stop",
    "actions": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "talk",
            "option": {
                "text": "Hello. This is outbound campaign's test calling. Please wait until the agent answer the call. Thank you.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ],
    "outplan_id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
    "next_campaign_id": "00000000-0000-0000-0000-000000000000",
    "tm_create": "2022-04-28 02:16:39.712142",
    "tm_update": "2022-04-30 17:53:51.685259",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Type

Campaign’s type.

Type

Description

call

The campaign will make a call to the destination with a flow.

flow

The campaign will execute flow with a destination.

Status

Campaign’s status.

Type

Description

stop

The campaign stopped.

stopping

The campaign is being stop. Waiting for dialing/process call’s termination.

run

The campaign is running. It will create a new call or flow execution.

Service level

The service level control the amount of campaigncalls. It appects to the campaign’s campaigncall creation.

The campaign makes a new campaigncall when…

Available agent > Current dialing campaign calls * Service level / 100

It valid only if the campaign has a valid queue_id.

End handle

Campaign’s outdial list end handle.

Type

Description

stop

The campaign will stop if the outdial has no more outdial target

continue

The campaign will continue to run after outdial has no more outdial target.

Campaigncall

Campaigncall

{
    "id": "<string>",
    "campaign_id": "<string>",
    "outplan_id": "<string>",
    "outdial_id": "<string>",
    "outdial_target_id": "<string>",
    "queue_id": "<string>",
    "activeflow_id": "<string>",
    "reference_type": "<string>",
    "reference_id": "<string>",
    "status": "<string>",
    "result": "<string>",
    "source": {
        ...
    },
    "destination": {
        ...
    },
    "destination_index": <number>,
    "try_count": <number>,
    "tm_create": "2022-04-29 07:01:45.808944",
    "tm_update": "2022-04-29 07:02:48.304704"
}

  • id: Campaigncall’s ID.

  • campaign_id: Campaign’s ID.

  • outplan_id: Outplan’s ID.

  • outdial_id: Outdial’s ID.

  • outdial_target_id: outdialtarget’s ID.

  • queue_id: Queue’s ID.

  • activeflow_id: Activeflow’s ID.

  • reference_type: Reference’s type. See detail here.

  • reference_id: Reference’s ID.

  • status: Campaigncall’s status. See detail here.

  • result: Campaigncall’s result. See detail here.

  • source: Source address info. See detail here.

  • destination: Destination address info. See detail here.

  • destination_index: Destination’s index.

  • try_count: Try count.

Example

{
    "id": "56347901-5bb9-422d-add5-5a2ca47fa737",
    "campaign_id": "183c0d5c-691e-42f3-af2b-9bffc2740f83",
    "outplan_id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "outdial_target_id": "f50b169d-ce02-4bc9-a6e7-bb632c71e450",
    "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
    "activeflow_id": "02aad54d-270e-43c7-82c5-bf42502c8bc6",
    "reference_type": "call",
    "reference_id": "a69189aa-7295-4c3a-b51f-df1dbbded5f6",
    "status": "done",
    "result": "success",
    "source": {
        "type": "tel",
        "target": "+821021656521",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destination": {
        "type": "tel",
        "target": "+821021656521",
        "target_name": "",
        "name": "",
        "detail": ""
    },
    "destination_index": 0,
    "try_count": 1,
    "tm_create": "2022-04-29 07:01:45.808944",
    "tm_update": "2022-04-29 07:02:48.304704"
}

Reference type

Campaigncall’s reference type.

Type

Description

none

Has no reference type.

call

The reference type is call. Reference id is call’s ID.

Status

Campaigncall’s status.

Type

Description

dialing

The campaigncall is dialing(not answered yet)

progressing

The campaigncall is progressing(the call answered)

done

The campaigncall is hungup

Result

Campaigncall’s result. The result is calculated by the final status/result of the referenced resource(call/sms/…).

For example, if the call ended with no_answer, the result will be calculated to the fail.

Type

Description

“”

Have no result yet.

success

The campaigncall ended successfully. The target’s status will be set to the done and will not make retry.

fail

The campaigncall ended unsuccesfully. The target’s status will be set to the idle and will make a retry.

The call hangup reason - result mapping table.

Call hangup reason

Calculated result

normal

success

All others

fail

Tutorial

Get list of campaigns

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/campaigns?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IXVCJ9.eyJjdXN0b21lciI6IntcImlkXCI6XCI1ZTRhMDY4MC04MDRlLTExZWMtODQ3Ny0yZmVhNTk2OGQ4NWJcIixcInVzZXJuYW1lXCI6XCJhZG1pblwiLFwibmFtZVwiOlwiYWRtaW5cIixcImRldGFpbFwiOlwiYWRtaW4gYWNjb3VudFwiLFwid2ViaG9va19tZXRob2RcIjpcIlBPU1RcIixcIndlYmhvb2tfdXJpXCI6XCJodHRwczovL2VueDM4NTN6M2pnMnEueC5waXBlZHJlYW0ubmV0L1wiLFwicGVybWlzc2lvbl9pZHNcIjpbXCIwMzc5NmUxNC03Y2I0LTExZWMtOWRiYS1lNzIwMjNlZmQxYzZcIl0sXCJ0bV9jcmVhdGVcIjpcIjIwMjItMDItMDEgMDA6MDA6MDAuMDAwMDAwXCIsXCJ0bV91cGRhdGVcIjpcIjIwMjItMDQtMTQgMDE6Mjg6NDYuNDU0ODk3XCIsXCJ0bV9kZWxldGVcIjpcIjk5OTktMDEtMDEgMDA6MDA6MDAuMDAwMDAwXCJ9IiwiZXhwIjoxNjUyMjkwNDYyfQ.-jaqJyjISxKmyDxRiFYopD0FA8vlZ_jJ1Sd9mqxCun0'

{
    "result": [
        {
            "id": "183c0d5c-691e-42f3-af2b-9bffc2740f83",
            "type": "call",
            "name": "test campaign",
            "detail": "test campaign detail",
            "status": "stop",
            "service_level": 100,
            "end_handle": "stop",
            "actions": [
                {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "next_id": "00000000-0000-0000-0000-000000000000",
                    "type": "talk",
                    "option": {
                        "text": "Hello. This is outbound campaign's test calling. Please wait until the agent answer the call. Thank you.",
                        "gender": "female",
                        "language": "en-US"
                    }
                }
            ],
            "outplan_id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
            "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
            "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
            "next_campaign_id": "00000000-0000-0000-0000-000000000000",
            "tm_create": "2022-04-28 02:16:39.712142",
            "tm_update": "2022-04-30 17:53:51.685259",
            "tm_delete": "9999-01-01 00:00:00.000000"
        }
    ],
    "next_page_token": "2022-04-28 02:16:39.712142"
}

Get detail of campaign

Example

$ curl --location --request GET 'https://api.voipbin.net/v1.0/campaigns/183c0d5c-691e-42f3-af2b-9bffc2740f83?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lciI6IntcImlkXCI6XCI1ZTRhMDY4MC04MDRlLTExZWMtODQ3Ny0yZmVhNTk2OGQ4NWJcIixcInVzZXJuYW1lXCI6XCJhZG1pblwiLFwibmFtZVwiOlwiYWRtaW5cIixcImRldGFpbFwiOlwiYWRtaW4gYWNjb3VudFwiLFwid2ViaG9va19tZXRob2RcIjpcIlBPU1RcIixcIndlYmhvb2tfdXJpXCI6XCJodHRwczovL2VueDM4NTN6M2pnMnEueC5waXBlZHJlYW0ubmV0L1wiLFwicGVybWlzc2lvbl9pZHNcIjpbXCIwMzc5NmUxNC03Y2I0LTExZWMtOWRiYS1lNzIwMjNlZmQxYzZcIl0sXCJ0bV9jcmVhdGVcIjpcIjIwMjItMDItMDEgMDDAwMDAwXCIsXCJ0bV91cGRhdGVcIjpcIjIwMjItMDQtMTQgMDE6Mjg6NDYuNDU0ODk3XCIsXCJ0bV9kZWxldGVcIjpcIjk5OTktMDEtMDEgMDA6MDA6MDAuMDAwMDAwXCJ9IiwiZXhwIjoxNjUyMjkwNDYyfQ.-jaqJyjISxKmyDxRiFYopD0FA8vlZ_jJ1Sd9mqxCun0'

{
    "id": "183c0d5c-691e-42f3-af2b-9bffc2740f83",
    "type": "call",
    "name": "test campaign",
    "detail": "test campaign detail",
    "status": "stop",
    "service_level": 100,
    "end_handle": "stop",
    "actions": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "next_id": "00000000-0000-0000-0000-000000000000",
            "type": "talk",
            "option": {
                "text": "Hello. This is outbound campaign's test calling. Please wait until the agent answer the call. Thank you.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ],
    "outplan_id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb",
    "next_campaign_id": "00000000-0000-0000-0000-000000000000",
    "tm_create": "2022-04-28 02:16:39.712142",
    "tm_update": "2022-04-30 17:53:51.685259",
    "tm_delete": "9999-01-01 00:00:00.000000"
}

Create a new campaign

Example

$ curl --location --request POST 'https://api.voipbin.net/v1.0/campaigns?token=eyJhbGciOiJIUzI1NiIsInR5cCIJ9.eyJjdXN0b21lciI6IntcImlkXCI6XCI1ZTRhMDY4MC04MDRlLTExZWMtODQ3Ny0yZmVhNTk2OGQ4NWJcIixcInVzZXJuYW1lXCI6XCJhZG1pblwiLFwibmFtZVwiOlwiYWRtaW5cIixcImRldGFpbFwiOlwiYWRtaW4gYWNjb3VudFwiLFwid2ViaG9va19tZXRob2RcIjpcIlBPU1RcIixcIndlYmhvb2tfdXJpXCI6XCJodHRwczovL2VueDM4NTN6M2pnMnEueC5waXBlZHJlYW0ubmV0L1wiLFwicGVybWlzc2lvbl9pZHNcIjpbXCIwMzc5NmUxNC03Y2I0LTExZWMtOWRiYS1lNzIwMjNlZmQxYzZcIl0sXCJ0bV9jcmVhdGVcIjpcIjIwMjItMDItMDEgMDA6MDA6MDAuMDAwMDAwXCIsXCJ0bV91cGRhdGVcIjpcIjIwMjItMDQtMTQgMDE6Mjg6NDYuNDU0ODk3XCIsXCJ0bV9kZWxldGVcIjpcIjk5OTktMDEtMDEgMDA6MDA6MDAuMDAwMDAwXCJ9IiwiZXhwIjoxNjUyMjkwNDYyfQ.-jaqJyjISxKmyDxRiFYopD0FA8vlZ_jJ1Sd9mqxCun0' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test campaign",
    "detail": "test campaign detail",
    "type": "call",
    "service_level": 100,
    "end_handle": "stop",
    "actions": [
        {
            "type": "talk",
            "option": {
                "text": "Hello. This is outbound campaign's test calling. Please wait until the agent answer the call. Thank you.",
                "gender": "female",
                "language": "en-US"
            }
        }
    ],
    "outplan_id": "d5fb7357-7ddb-4f2d-87b5-8ccbfd6c039e",
    "outdial_id": "40bea034-1d17-474d-a5de-da00d0861c69",
    "queue_id": "99bf739a-932f-433c-b1bf-103d33d7e9bb"
}'