Tutorial basic

Prerequisites

Before working with flows, you need:

An authentication token. Obtain one via POST /auth/login or use an access key from GET /accesskeys.
(For update/delete) A flow ID (UUID). Obtain from GET /flows or the response of POST /flows.

Note

AI Implementation Hint

When creating a flow via POST /flows, action id fields are optional. The server auto-generates UUIDs for actions that lack explicit IDs. Only set action IDs when you need to reference them from goto, branch, or condition_* actions using target_id or target_ids. Flow changes (update/delete) do not affect calls already in progress – they only apply to future executions.

Get list of flows

Gets the list of registered flows.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows?token=<YOUR_AUTH_TOKEN>'

{
    "result": [
        {
            "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
            "name": "default flow",
            "detail": "default flow for voipbin incoming calls",
            "actions": [
                {
                    "id": "b34aa8a4-0b30-11eb-8016-1f5bc75b1c04",
                    "type": "play",
                    "option": {
                        "stream_url": [
                            "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                        ]
                    }
                },
                {
                    "id": "57a3dcd2-0b2b-11eb-94a6-a7129b64693c",
                    "type": "play",
                    "option": {
                        "stream_url": [
                            "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                        ]
                    }
                }
            ],
            "tm_create": "2020-10-11 01:00:00.000001",
            "tm_update": "",
            "tm_delete": ""
        },
        {
            "id": "af9dae94-ef07-11ea-a101-8f52e568f39b",
            "name": "test flow",
            "detail": "manual flow test",
            "actions": [
                {
                    "id": "00000000-0000-0000-0000-000000000000",
                    "type": "echo"
                }
            ],
            "tm_create": "2020-09-04 23:53:14.496918",
            "tm_update": "",
            "tm_delete": ""
        }
    ],
    "next_page_token": "2020-09-04 23:53:14.496918"
}

Get detail of specified flow

Gets the detail of registered flows.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?token=<YOUR_AUTH_TOKEN>'

{
    "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "name": "default flow",
    "detail": "default flow for voipbin incoming calls",
    "actions": [
        {
            "id": "b34aa8a4-0b30-11eb-8016-1f5bc75b1c04",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "id": "57a3dcd2-0b2b-11eb-94a6-a7129b64693c",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ],
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "",
    "tm_delete": ""
}

Create a flow

Create a new flow for incoming call requests. When the call is incoming, this flow will answer the call first, then speak the welcome text.

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/flows?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test flow",
    "detail": "test voipbin flow example",
    "actions": [
        {
            "type": "answer"
        },
        {
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin'\''s service. thank you.",
                "language": "en-US"
            }
        }
    ]
}'

{
    "id": "24013a0e-d15b-4b5e-9a96-04221a8c6a15",
    "name": "test flow",
    "detail": "test voipbin flow example",
    "actions": [
        {
            "id": "9461bda1-54fd-4e27-ab04-4186c6f72830",
            "type": "answer"
        },
        {
            "id": "69af787e-f5fa-4a1b-9d12-f0b43b86dae6",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "language": "en-US"
            }
        }
    ],
    "tm_create": "2021-02-04 06:47:01.139361",
    "tm_update": "",
    "tm_delete": ""
}

Update the flow

Update an existing flow with the given information. This doesn’t affect existing calls. Flow changes will only affect new calls.

$ curl -k --location --request PUT 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?token=<YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "test flow update",
    "detail": "test voipbin flow example update",
    "actions": [
        {
            "type": "answer"
        },
        {
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin'\''s service. thank you.",
                "language": "en-US"
            }
        },
        {
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ]
}'

{
    "id": "decc2634-0b2a-11eb-b38d-87a8f1051188",
    "name": "test flow update",
    "detail": "test voipbin flow example update",
    "actions": [
        {
            "id": "be682498-e57e-41e9-b210-a578f9c044c5",
            "type": "answer"
        },
        {
            "id": "6669bfdd-a7b0-45e6-9a8d-db6bb898159f",
            "type": "talk",
            "option": {
                "text": "hello. welcome to voipbin. This is test message. Please enjoy the voipbin's service. thank you.",
                "language": "en-US"
            }
        },
        {
            "id": "099b60c1-7b95-4d69-8cac-df11a992ee11",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/voipbin/welcome.wav"
                ]
            }
        },
        {
            "id": "89fa5091-a192-4758-8a29-316776ead8fe",
            "type": "play",
            "option": {
                "stream_url": [
                    "https://github.com/pchero/asterisk-medias/raw/master/samples_codec/pcm_samples/example-mono_16bit_8khz_pcm.wav"
                ]
            }
        }
    ],
    "tm_create": "2020-10-11 01:00:00.000001",
    "tm_update": "2021-02-05 13:08:56.113036",
    "tm_delete": ""
}

Delete the flow

Delete an existing flow by its flow ID. This doesn’t affect existing calls. Flow changes will only affect new calls.

$ curl -k --location --request DELETE 'https://api.voipbin.net/v1.0/flows/af9dae94-ef07-11ea-a101-8f52e568f39b?token=<YOUR_AUTH_TOKEN>'

Note

AI Implementation Hint

The DELETE request uses the DELETE HTTP method, not GET. A successful deletion returns HTTP 204 No Content. The flow is soft-deleted (tm_delete is set) and will no longer appear in GET /flows list results, but calls already using this flow are not affected.