.. _flow-tutorial-basic: 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. .. code:: $ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows?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. .. code:: $ curl -k --location --request GET 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?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. .. code:: $ curl -k --location --request POST 'https://api.voipbin.net/v1.0/flows?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. .. code:: $ curl -k --location --request PUT 'https://api.voipbin.net/v1.0/flows/decc2634-0b2a-11eb-b38d-87a8f1051188?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. .. code:: $ curl -k --location --request DELETE 'https://api.voipbin.net/v1.0/flows/af9dae94-ef07-11ea-a101-8f52e568f39b?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.