© 2015 X2Engine Inc.

Difference between revisions of "Web API Reference (Legacy)"

From X2Engine
Jump to: navigation, search
(Usage)
 
(47 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
[[Category:Development]]
 
[[Category:Development]]
 +
'''This is the reference guide for the "legacy" API.''' While the legacy API will still remain in the app, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the [[REST API Reference]] page.
  
X2CRM features a remote API for inserting, updating, querying and deleting records via [[x2doc:ApiController|ApiController]], which (with few exceptions) responds in JSON format. The API can perform these operations with any subclass of X2Model. URLs (after the domain name and relative path to the [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/. In most calls to the API, authentication is required in the form of GET or POST parameters <tt>user</tt> and <tt>userKey</tt>, which are the username and API key (respectively) of a user in the CRM.  
+
X2Engine features a HTTP-based API for inserting, updating, querying and deleting records via [[x2doc:ApiController|ApiController]], which (with few exceptions) responds in JSON format. The API can perform these operations with any subclass of X2Model. URLs (after the domain name and relative path to the [http://httpd.apache.org/docs/2.2/mod/core.html#documentroot document root]) for web requests to the API begin with index.php/api/.  
 +
= Authenticating =
 +
In most calls to the API, authentication is required in the form of GET or POST parameters <tt>user</tt> and <tt>userKey</tt>, which are the username and API key (respectively) of a user in the CRM. In versions earlier than 2.9.1, these parameters are named <tt>authUser</tt> and <tt>authPassword</tt>, and authPassword is the password hash.  
  
= API Response =
+
== Getting and Setting API Keys ==
In the case of an error, the API will still respond in JSON format, and will set the HTTP response code according to the following rules
+
A user's API key can be set (or looked up) by the administrator, by (in the ''Users'' module) visiting the ''Update'' page for the given user.
  
 
+
= CRUD (Create, Read, Update &amp; Delete) API Methods =
= Usage =
+
The following API actions can be used with any subclass of X2Model (i.e. Contacts, Accounts, Opportunity, etc.) In the following reference table, the model class to be used for display purposes is <tt>Contacts</tt>, and the id (primary key) value is 5.
In the reference table here, the model class to be used is <tt>Contacts</tt>.
 
 
{|class="wikitable" align="left"
 
{|class="wikitable" align="left"
 
|-
 
|-
! scope="col" | Usage
+
! scope="col" | Use
 
! scope="col" | Method
 
! scope="col" | Method
 
! scope="col" | URL
 
! scope="col" | URL
 
! scope="col" | Authentication
 
! scope="col" | Authentication
! scope="col" | Request type(s)
+
! scope="col" | Request type/data expected
! scope="col" | Expected data
 
 
! scope="col" | Code
 
! scope="col" | Code
 
! scope="col" | Response properties
 
! scope="col" | Response properties
Line 22: Line 23:
 
|Create a new record
 
|Create a new record
 
|[[x2propdoc:ApiController.html#_actionCreate|actionCreate()]]
 
|[[x2propdoc:ApiController.html#_actionCreate|actionCreate()]]
|<tt>index.php/api/create/model/Contacts</tt>
+
|/create/model/Contacts
 
|With post data
 
|With post data
|<tt>POST</tt>
+
|<tt>POST</tt>; authentication &amp; model attributes together in a flat list as URL-encoded form data
|Form (post) data containing authentication and attributes (key-value) of the model to be created, together, as a flat list
+
|
|200 if successful, else 500
+
;200
 +
: Record successfully inserted
 +
;500
 +
: Model failed validation
 
|
 
|
 
;error
 
;error
Line 37: Line 41:
 
|Search for the first record matching one or more fields
 
|Search for the first record matching one or more fields
 
|[[x2propdoc:ApiController.html#_actionLookup|actionLookup()]]
 
|[[x2propdoc:ApiController.html#_actionLookup|actionLookup()]]
|<tt>index.php/api/lookup/model/Contacts</tt>
+
|/lookup/model/Contacts
 
|With post data
 
|With post data
|<tt>POST</tt>
+
|<tt>POST</tt>; Same as with the <tt>create</tt> action
|Similar to the <tt>create</tt> action
+
|
|200 if successful, else 404
+
;200
|If successful: attributes of the model as a flat list (indexed by attribute name) key-value pairs indexed by name. Otherwise: <tt>{"error":true,"message":"No item found with specified attributes."}</tt>
+
: found record
 +
;404
 +
: no record found
 +
|If successful: attributes of the model as a flat key-value pair list (indexed by attribute name). Otherwise:  
 +
;error
 +
: boolean / true
 +
;message
 +
: "No item found with specified attributes."
 
|-
 
|-
|Retrieve a record based on its primary key ('''5''', for instance)
+
|Retrieve a record by primary key
 
|[[x2propdoc:ApiController.html#_actionView|actionView()]]
 
|[[x2propdoc:ApiController.html#_actionView|actionView()]]
|<tt>index.php/api/view/Contacts/id/5</tt>
+
|/view/Contacts/id/5
|As query parameters, i.e. <tt>index.php/api/view/Contacts/id/5?user=yourusername&userKey=Y0URU53RK3Y</tt>
+
|As additional query parameters appended to the URL
 
|<tt>GET</tt>
 
|<tt>GET</tt>
|200 if successful, else 404 if no record found, else 400 if the primary key is not included properly or specified
+
|
 +
;200
 +
: Record found with specified primary key
 +
;400
 +
: The primary key is not included properly or specified
 +
;404
 +
: No record found
 
|Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
 
|Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
 
;error
 
;error
Line 56: Line 73:
 
: A string containing an explanation of what went wrong
 
: A string containing an explanation of what went wrong
 
|-
 
|-
 +
|Update a preexisting record
 
|[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate()]]
 
|[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate()]]
|<tt>index.php/api/update</tt>
+
|/update/model/Contacts/id/5
|yes
+
|With post data
|Updates a record
+
|<tt>POST</tt>; same as with <tt>create</tt> method
 +
|
 +
;200
 +
: Record successfully updated
 +
;404
 +
: Record to be updated does not exist
 +
;400
 +
: Primary key is missing from query parameters
 +
;500
 +
: Model failed validation during update
 +
|Same as with <tt>create</tt> action
 
|-
 
|-
 +
|Delete a record
 
|[[x2propdoc:ApiController.html#_actionDelete|actionDelete()]]
 
|[[x2propdoc:ApiController.html#_actionDelete|actionDelete()]]
|<tt>index.php/api/delete</tt>
+
|/delete/model/Contacts/id/5
|yes
+
|With post data
|Deletes a record
+
|<tt>POST</tt>; authentication data
|-
+
|
|[[x2propdoc:ApiController.html#_actionVoip|actionVoip()]]
+
;200
|<tt>index.php/api/voip</tt>
+
: Record successfully deleted
|no
+
;404
|Notifies the assignee of a contact having called (if the phone number matches).<br> Requires only the "phone" field, as a GET parameter, it being a 10+ digit phone number.
+
: Record to be deleted does not exist
 +
;400
 +
: Primary key is missing from query parameters
 +
;500
 +
: Record could not be deleted
 +
|
 +
;message
 +
: "1" if successful; else, an error message
 +
;error
 +
: boolean / true if and only if successful
 
|-
 
|-
 
|}
 
|}
  
 +
== Attribute Input Format ==
 +
The input to the API will be processed in the same way that it is within the application, that is to say, using the method [[x2propdoc:X2Model.html#_setX2Fields|X2Model.setX2Fields()]]. In particular, the method [[x2propdoc:Fields.html#_parseValue|Fields.parseValue()]] is used for processing and transforming the data before it is recorded in the database. The <tt>case</tt> statement in that method shows how each type of field is processed (see [[X2Model_and_Dynamic_Fields|X2Model and Dynamic Fields]] for more information on field types and how fields are dynamically managed)
  
 +
= Miscellaneous API actions =
  
The post data variables should be named according to the column names of the model for which the API being called. When making API calls, the same validation rules as in normal use of the app also apply. In the case that the input does not pass validation, the API will respond with the validation errors.
+
== Managing relationships betweeen records ==
 
+
One can create, get lists of and delete relationships between records in X2Engine by using the [[x2propdoc:ApiController.html#_actionRelationship|actionRelationship()]] method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL: <tt>index.php/api/relationship/model/Contacts</tt> (for relating to models of class <tt>Contacts</tt>). This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:
== Authenticating ==
+
{|class="wikitable"
Using the API requires authentication credentials for the web application in the form of two post data fields: <tt>user</tt> and <tt>userKey</tt>, containing the username and API key of that user (versions 2.9.1 and later), or <tt>authUser</tt> and <tt>authPassword</tt>, containing the username and password hash (versions earlier than 2.9.1), respectively. A user's API key can be set by the administrator in the User module by visiting the update page for the given user.
 
 
 
== Available API functions ==
 
(See also the documentation on [[x2doc:ApiController|ApiController]])
 
 
 
The methods of [[x2doc:ApiController|ApiController]] used for creating, querying, viewing (by ID), updating and deleting records are:
 
 
 
{|class="wikitable" align="center"
 
 
|-
 
|-
! scope="col" | Method
+
! scope="col" | Use
! scope="col" | Base URL
+
! scope="col" | Request type/data expected
! scope="col" | ID required
+
! scope="col" | Codes
! scope="col" | Usage
+
! scope="col" | Response
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionCreate|actionCreate()]]
+
|Create a relationship
|<tt>index.php/api/create</tt>
+
|<tt>POST</tt> with url-encoded form data: <tt>secondType</tt> (model class of target), <tt>firstId</tt> (id of the first model), and <tt>secondId</tt> (id of the target model), in addition to authentication parameters.
|no
+
|
|Creates a new record
+
;200
 +
: The relationship was created successfully or already exists
 +
;400
 +
: The relationship failed validation (most likely because the target model records do not exist)
 +
;500
 +
: Failed to insert relationship record for some other reason, i.e. database error
 +
|
 +
;error
 +
: false/true based on whether the relation was inserted
 +
;message
 +
: String; message telling whether the relationship exists or not, or if there was an error
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionLookup|actionLookup()]]
+
|Get relationships between two models
|<tt>index.php/api/lookup</tt>
+
|<tt>GET</tt>, with query parameters same as those in creating relationships, and authentication. However, parameters may be omitted to make the query more inclusive, i.e. omitting <tt>secondId</tt> but setting <tt>firstId</tt> to 5, <tt>model</tt> to "Accounts" and <tt>secondType</tt> to "Contacts" will show all relationships between the Account record with id=5 and contact records.
|no
+
|
|Searches for a record based on one or more fields
+
;200
 +
: Relationships exist
 +
;404
 +
: No relationships found
 +
|A list (JSON-encoded, of course) of relationship records (each itself an attribute -> value pair list)
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionView|actionView()]]
+
|Delete a relationship
|<tt>index.php/api/view</tt>
+
|<tt>DELETE</tt>, with everything defined in the query parameters. Behavior is similar to the <tt>GET</tt> method; in fact, it can delete multiple relationships at the same time, similarly omitting parameters to make the query more inclusive.
|yes
+
|
|Views a record
+
;200
 +
: Relationship(s) successfully deleted
 +
;404
 +
: No relationships found were deleted
 +
;500
 +
: Some relationship(s) could not be deleted due to a database error
 +
|
 +
;message
 +
: A string status message for the request
 +
;error
 +
: boolean (true on success, false on failure)
 +
|}
 +
 
 +
== Tagging Records ==
 +
Child classes of X2Model can be tagged, and tagging can be done through the API action [[x2propdoc:ApiController.html#_actionTags|actionTags()]] at the URL <tt>index.php/api/tags/model/Contacts/id/5</tt> (to add tags to contact #5, for instance). The following describes how to use the action:
 +
{|class="wikitable"
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionUpdate|actionUpdate()]]
+
! scope="col" | Use
|<tt>index.php/api/update</tt>
+
! scope="col" | Request type/data expected
|yes
+
! scope="col" | Codes
|Updates a record
+
! scope="col" | Response
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionDelete|actionDelete()]]
+
|Tag a model
|<tt>index.php/api/delete</tt>
+
|<tt>POST</tt> with url-encoded form data: <tt>tag</tt> (if adding one tag) or <tt>tags</tt> (if adding multiple tags at once, and in this case, it must be a JSON-encoded list), in addition to authentication parameters.
|yes
+
|
|Deletes a record
+
;200
 +
: Tags applied
 +
;400
 +
: Required parameter is missing, or invalid model
 +
;404
 +
: Model not found
 +
;500
 +
: Failed to add tags for some reason, i.e. database error
 +
|
 +
;error
 +
: false/true based on whether the tags were successfully inserted
 +
;message
 +
: String; status message
 
|-
 
|-
|[[x2propdoc:ApiController.html#_actionVoip|actionVoip()]]
+
|Get tags on a model
|<tt>index.php/api/voip</tt>
+
|<tt>GET</tt>, with the model class and id specified in the query parameters as when updating a model (see the previous section, on CRUD methods).
|no
+
|
|Notifies the assignee of a contact having called (if the phone number matches).<br> Requires only the "phone" field, as a GET parameter, it being a 10+ digit phone number.
+
;200
 +
: Almost every response barring authentication failure
 +
;400
 +
: Invalid model is specified
 +
;404
 +
: Model not found
 +
|A JSON-encoded list of tags
 
|-
 
|-
 +
|Delete one or more tags
 +
|<tt>DELETE</tt>, with everything defined in the query parameters. The tags may be a url-encoded list, or a string (single tag to delete)
 +
|
 +
;200
 +
: Tag(s) removed
 +
;400
 +
: Parameter missing
 +
;404
 +
: No tags were deleted; the model did not have specified tags (or, model not found)
 +
|
 +
;message
 +
: A string status message for the request
 +
;error
 +
: boolean (true on success, false on failure)
 
|}
 
|}
  
== Specifying Model ==
+
Example: add tag "customer" to the contact with ID equal to 71:
The API '''requires''' specifying the model for which the transaction will be performed as a GET parameter with key "model", with <tt>actionVoip</tt> being the only current exception. Per the URL format rule of X2CRM, which is "path" (see [[yii:CUrlManager|CUrlManager]] for more information), the full URL of the request will be: <code>index.php/api/[method]/model/[model name]</code>. So, for example, an API call to create a new contact record should use <code>index.php/api/create/model/Contacts</code>
+
* Make the request to <tt>index.php/api/tags/model/Contacts/id/71</tt>
 +
* Request type POST
 +
* Send with post data "user","userKey" (authentication parameters) and "tag" set to "customer".
 +
Or, with two tags, "customer" and "active":
 +
* Request to <tt>index.php/api/tags/model/Contacts/id/71</tt>
 +
* Request type POST
 +
* Post data includes the usual authentication parameters, and "tags", which should be the JSON-encoded list of tags: <syntaxhighlight lang="javascript">["customer","active"]</syntaxhighlight>
 +
 
 +
== Inbound VoIP call notifications ==
 +
PBX systems that are connected to the internet, especially if they are based on [[wiki:Asterisk_(PBX)|Asterisk]], will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2Engine. The action api/voip, which does not require authentication, is the most basic way of doing so where all that is necessary is to notify sales reps when a contact is calling. This gives the rep a window of few seconds (depending on the dialplan, and if the caller is typing in someone's extension directly) to get ready to receive the call when it finally reaches them. It creates notifications for all users (if assigned to "Anyone"), an activity feed event, and if the contact is assigned to someone, it opens a new window with the record on screen in that rep's web browser.
 +
 
 +
To use it, make a GET request to index.php/api/voip/data/{phone number}, where {phone number} is the caller ID (without spaces, parentheses or dashes) calling in. Note, it may yield better results if the country code is ommitted; the search for contacts is based on serialized phone numbers but also returns the first partial match. So, as long as the <tt>data</tt> parameter is a unique part of a phone number, it won't match the incorrect contact record.
 +
 
 +
More information on this method: [[x2propdoc:ApiController.html#_actionVoip|actionVoip()]].
 +
 
 +
== Get a list of all users in the app ==
 +
The method [[x2propdoc:ApiController.html#_actionListUsers|actionListUsers()]] (accessed via GET at /api/listUsers) requires authentication (as query parameters) and will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action. It returns, upon success, a JSON-encoded list of users, each user a list of attribute name to attribute value key/value pairs (according to the columns of the <tt>x2_users</tt> table. The <tt>password</tt> and <tt>userKey</tt> fields, however, are ommitted from the attributes of all users.
  
== Usage Example ==
+
= Security Considerations =
The file [https://github.com/X2Engine/X2Engine/blob/master/x2engine/leadCapture.php leadCapture.php] in the web root of the codebase contains a few noteworthy examples of API calls. Of particular significance is the necessity of creating a contact first and then using <tt>lookup</tt> to obtain its numeric ID in order to create an action associated with that contact.
+
It is in general considered a best practice to securely encrypt web traffic to your web server with HTTP over SSL (HTTPS). Without this, API authentication credentials will be sent directly to the server in plain text, and thus vulnerable to exposure via man-in-the-middle (MITM) attacks and packet sniffing. Note, however, that if HTTPS is not used on the server, normal web-browser authentication would also be vulnerable to this kind of attack anyway, because the session ID stored in the cookie can similarly be stolen and used to access the system as any given user.
  
(section in progress)
+
If SSL-protected HTTP is not an option due to the cost, it is thus recommended that you keep all of your API requests within the same server or intranet and/or behind a firewall, as that would mean that both the origin and target of the API web request would be within a protected network area, and thus would more difficult to access.

Latest revision as of 02:00, 2 May 2014

This is the reference guide for the "legacy" API. While the legacy API will still remain in the app, and bugs affecting it can/will still be fixed, no new features will be developed for it. For up-to-date information on X2Engine's REST API, see the REST API Reference page.

X2Engine features a HTTP-based API for inserting, updating, querying and deleting records via ApiController, which (with few exceptions) responds in JSON format. The API can perform these operations with any subclass of X2Model. URLs (after the domain name and relative path to the document root) for web requests to the API begin with index.php/api/.

Authenticating

In most calls to the API, authentication is required in the form of GET or POST parameters user and userKey, which are the username and API key (respectively) of a user in the CRM. In versions earlier than 2.9.1, these parameters are named authUser and authPassword, and authPassword is the password hash.

Getting and Setting API Keys

A user's API key can be set (or looked up) by the administrator, by (in the Users module) visiting the Update page for the given user.

CRUD (Create, Read, Update & Delete) API Methods

The following API actions can be used with any subclass of X2Model (i.e. Contacts, Accounts, Opportunity, etc.) In the following reference table, the model class to be used for display purposes is Contacts, and the id (primary key) value is 5.

Use Method URL Authentication Request type/data expected Code Response properties
Create a new record actionCreate() /create/model/Contacts With post data POST; authentication & model attributes together in a flat list as URL-encoded form data
200
Record successfully inserted
500
Model failed validation
error
true if and only if the new record was created successfully
model
attributes of the model as key-value pairs (indexed by attribute name)
modelErrors
validation errors for each attribute, if applicable
Search for the first record matching one or more fields actionLookup() /lookup/model/Contacts With post data POST; Same as with the create action
200
found record
404
no record found
If successful: attributes of the model as a flat key-value pair list (indexed by attribute name). Otherwise:
error
boolean / true
message
"No item found with specified attributes."
Retrieve a record by primary key actionView() /view/Contacts/id/5 As additional query parameters appended to the URL GET
200
Record found with specified primary key
400
The primary key is not included properly or specified
404
No record found
Attributes of the model as a flat list indexed by attribute name, if successful. Otherwise:
error
boolean / true, indicating an error
message
A string containing an explanation of what went wrong
Update a preexisting record actionUpdate() /update/model/Contacts/id/5 With post data POST; same as with create method
200
Record successfully updated
404
Record to be updated does not exist
400
Primary key is missing from query parameters
500
Model failed validation during update
Same as with create action
Delete a record actionDelete() /delete/model/Contacts/id/5 With post data POST; authentication data
200
Record successfully deleted
404
Record to be deleted does not exist
400
Primary key is missing from query parameters
500
Record could not be deleted
message
"1" if successful; else, an error message
error
boolean / true if and only if successful

Attribute Input Format

The input to the API will be processed in the same way that it is within the application, that is to say, using the method X2Model.setX2Fields(). In particular, the method Fields.parseValue() is used for processing and transforming the data before it is recorded in the database. The case statement in that method shows how each type of field is processed (see X2Model and Dynamic Fields for more information on field types and how fields are dynamically managed)

Miscellaneous API actions

Managing relationships betweeen records

One can create, get lists of and delete relationships between records in X2Engine by using the actionRelationship() method. Of all the API methods, this is one of the most recently-created; creation, retrieval and deletion of relationships all happen through the same URL: index.php/api/relationship/model/Contacts (for relating to models of class Contacts). This is an effort to shift in the direction of an ultimately more REST-ful and clean API. The following table describes its uses and responses:

Use Request type/data expected Codes Response
Create a relationship POST with url-encoded form data: secondType (model class of target), firstId (id of the first model), and secondId (id of the target model), in addition to authentication parameters.
200
The relationship was created successfully or already exists
400
The relationship failed validation (most likely because the target model records do not exist)
500
Failed to insert relationship record for some other reason, i.e. database error
error
false/true based on whether the relation was inserted
message
String; message telling whether the relationship exists or not, or if there was an error
Get relationships between two models GET, with query parameters same as those in creating relationships, and authentication. However, parameters may be omitted to make the query more inclusive, i.e. omitting secondId but setting firstId to 5, model to "Accounts" and secondType to "Contacts" will show all relationships between the Account record with id=5 and contact records.
200
Relationships exist
404
No relationships found
A list (JSON-encoded, of course) of relationship records (each itself an attribute -> value pair list)
Delete a relationship DELETE, with everything defined in the query parameters. Behavior is similar to the GET method; in fact, it can delete multiple relationships at the same time, similarly omitting parameters to make the query more inclusive.
200
Relationship(s) successfully deleted
404
No relationships found were deleted
500
Some relationship(s) could not be deleted due to a database error
message
A string status message for the request
error
boolean (true on success, false on failure)

Tagging Records

Child classes of X2Model can be tagged, and tagging can be done through the API action actionTags() at the URL index.php/api/tags/model/Contacts/id/5 (to add tags to contact #5, for instance). The following describes how to use the action:

Use Request type/data expected Codes Response
Tag a model POST with url-encoded form data: tag (if adding one tag) or tags (if adding multiple tags at once, and in this case, it must be a JSON-encoded list), in addition to authentication parameters.
200
Tags applied
400
Required parameter is missing, or invalid model
404
Model not found
500
Failed to add tags for some reason, i.e. database error
error
false/true based on whether the tags were successfully inserted
message
String; status message
Get tags on a model GET, with the model class and id specified in the query parameters as when updating a model (see the previous section, on CRUD methods).
200
Almost every response barring authentication failure
400
Invalid model is specified
404
Model not found
A JSON-encoded list of tags
Delete one or more tags DELETE, with everything defined in the query parameters. The tags may be a url-encoded list, or a string (single tag to delete)
200
Tag(s) removed
400
Parameter missing
404
No tags were deleted; the model did not have specified tags (or, model not found)
message
A string status message for the request
error
boolean (true on success, false on failure)

Example: add tag "customer" to the contact with ID equal to 71:

  • Make the request to index.php/api/tags/model/Contacts/id/71
  • Request type POST
  • Send with post data "user","userKey" (authentication parameters) and "tag" set to "customer".

Or, with two tags, "customer" and "active":

  • Request to index.php/api/tags/model/Contacts/id/71
  • Request type POST
  • Post data includes the usual authentication parameters, and "tags", which should be the JSON-encoded list of tags:
    ["customer","active"]
    

Inbound VoIP call notifications

PBX systems that are connected to the internet, especially if they are based on Asterisk, will have the ability to run scripts within their call flow. This opens the possibility of integrating phone systems with X2Engine. The action api/voip, which does not require authentication, is the most basic way of doing so where all that is necessary is to notify sales reps when a contact is calling. This gives the rep a window of few seconds (depending on the dialplan, and if the caller is typing in someone's extension directly) to get ready to receive the call when it finally reaches them. It creates notifications for all users (if assigned to "Anyone"), an activity feed event, and if the contact is assigned to someone, it opens a new window with the record on screen in that rep's web browser.

To use it, make a GET request to index.php/api/voip/data/{phone number}, where {phone number} is the caller ID (without spaces, parentheses or dashes) calling in. Note, it may yield better results if the country code is ommitted; the search for contacts is based on serialized phone numbers but also returns the first partial match. So, as long as the data parameter is a unique part of a phone number, it won't match the incorrect contact record.

More information on this method: actionVoip().

Get a list of all users in the app

The method actionListUsers() (accessed via GET at /api/listUsers) requires authentication (as query parameters) and will return with HTTP code 403 if the user used for authenticating does not have permission to the UsersIndex RBAC action. It returns, upon success, a JSON-encoded list of users, each user a list of attribute name to attribute value key/value pairs (according to the columns of the x2_users table. The password and userKey fields, however, are ommitted from the attributes of all users.

Security Considerations

It is in general considered a best practice to securely encrypt web traffic to your web server with HTTP over SSL(a.k.a Transport Layer Security) a method of connecting to a remote network host that encrypts traffic on any given network protocol that uses it. (HTTPS). Without this, API authentication credentials will be sent directly to the server in plain text, and thus vulnerable to exposure via man-in-the-middle (MITM) attacks and packet sniffing. Note, however, that if HTTPS is not used on the server, normal web-browser authentication would also be vulnerable to this kind of attack anyway, because the session ID stored in the cookie can similarly be stolen and used to access the system as any given user.

If SSL(a.k.a Transport Layer Security) a method of connecting to a remote network host that encrypts traffic on any given network protocol that uses it.-protected HTTP is not an option due to the cost, it is thus recommended that you keep all of your API requests within the same server or intranet and/or behind a firewall, as that would mean that both the origin and target of the API web request would be within a protected network area, and thus would more difficult to access.