====== API Documentation ======

celitoVoice is built on a completely open API. Everything that can be done through the web portal can be done through the API, allowing a developer to easily integrate the phone system with any internal applications you may have. 

<WRAP info>API access is not enabled by default. Please contact your Account Executive to receive details on gaining access to the API.</WRAP>
<WRAP alert>By accessing or using the celitoVoice API, you agree to be bound by our API TOS {{ :downloads:api_waiver-20170606.pdf|available here}}.</WRAP>


===== Live Documentation =====
We have a documentation guide that is updated automatically as changes are made to the API. It also features the ability to send sample requests to allow for easy testing. The documentation begins with details on how to request your OAuth2 token (required to make any calls to the API) and then goes on to describe all of the different available calls.

http://api.celitovoice.net/ns-api/apidoc/

===== API Servers =====
celito has multiple redundant servers that are geo-redundant. You have the ability to point your API calls directly to one instance, however servers may go down for maintenance without warning. It is highly recommended that you use the server listed below, rather than any specific ones mentioned in the documentation.

^ Server                                             ^ Purpose               ^
| %%https://api.celitovoice.net/ns-api/oauth2/token/%%  | OAuth2 token request  |
| %%https://api.celitovoice.net/ns-api/%%               | All other requests    |

===== Yealink Phones - URL Hooks =====
If you are using Yealink phones (recommended) then you also have access to action URLs and URL hooks. This is a way to get information directly from the phone without having to interface with the celitoVoice API at all. This works by programming the phones with a URL that is called automatically based on a defined trigger event.

There are a large number of different events that can have a trigger assigned to them, and a lot of different variables. A full guide from Yealink on the different options is attached below.

==== Example ====
^ Event: Call Established   | Triggered when the phone establishes a call                                                                                            |
^ Variable: $active_user    | The user part of the SIP URI for the current account when the phone places a call, receives an incoming call or establishes a call.    |
^ Variable: $display_local  | The display name of the caller when the phone places a call. The display name of the callee when the phone receives an incoming call.  |
^ URL                       | %%https://example.yourdomain.com/call_established.php?user=$active_user&display=$display_local%%                                       |

==== Documentation (from Yealink) ====
<WRAP download 60%>
{{ :downloads:yealink-action-url.pdf|yealink-action-url.pdf}}
</WRAP>

  
===== Related Articles =====
  * {{ :downloads:api_waiver-20170606.pdf|API Terms of Service}}
{{topic>api development}}

{{tag>api development}}