Talkety XML API

The XML API is an interface to Talkety‘s VoIP services based on the HTTP protocol and XML.

The base URL to the XML API is:

  https://api.talkety.com/xml/v1/<your_app_key>

To interact with the XML API you append the name of an action you wish to perform and related parameters. Both GET and POST request methods are supported.

For example, the following request initiates a call between the phone numbers 1-123-4567 890 and 1-987-6543 210 and returns the result in XML format:

 https://api.talkety.com/xml/v1/84f4097bb4955c6c58ba452ece41c075/call_connect?src=11234567890&dst=19876543210

Authentication

To interact with the XML API, you need to provide Talkety login credentials using standard HTTP Basic Authentication.

The XML schema

Call objects

There are two types of calls:

Call

A regular VoIP call between two numbers.

  <?xml version="1.0" encoding="UTF-8"?>
  <call>
    <id>148</id>
    <call_start>2007-02-26T23:54:28Z</call_start>
    <call_end></call_end>
    <call_status>connected</call_status>
    <call_via>api</call_via>
    <dst>9876543210</dst>
    <dst_name>USA</dst_name>
    <src>1234567890</src>
    <src_name>USA</src_name>
    <duration>2706</duration>
    <total_costs>1.94022</total_costs>
  </call>

Conference

A conference call between multiple numbers. The conference itself only serves as a container for individual calls which represent the physical connections to each number.

  <?xml version="1.0" encoding="UTF-8"?>
  <conference>
    <id>263</id>
    <conference_start>2007-02-26T23:54:28Z</call_start>
    <conference_end></call_end>
    <conference_status>connected</call_status>
    <conference_via>api</conference_via>
    <dst>webconference</dst>
    <dst_name>webconference</dst_name>
    <src>1234567890</src>
    <src_name>USA</src_name>
    <duration>2706</duration>
    <total_costs>1.94022</total_costs>
    <calls>
      <call owner="true">
        <id>149</id>
        <call_start>2007-02-26T23:54:28Z</call_start>
        <call_end></call_end>
        <call_status>connected</call_status>
        <dst>1234567890</dst>
        <dst_name>USA</dst_name>
        <src>1234567890</src>
        <src_name>USA</src_name>
        <duration>2705</duration>
        <total_costs>0.4869</total_costs>
      </call>
      <call>
        <id>150</id>
        ...
      </call>
      ...
    </calls>
  </conference>

Response status messages

Success status

  <?xml version="1.0" encoding="UTF-8"?>
  <success>
    <call_id>13212</call_id>
  </success>

An XML node success with child node call_id or conference_id, specifying the id of the referenced call or conference.

Error status

  <?xml version="1.0" encoding="UTF-8"?>
  <error>
    <code>123</code>
    <message>The error message here</message>
  </error>

An XML node error with child nodes code and message, detailing error code and error message.

So far the following error messages exist (may change in future versions of the API):

• 10: "Incorrect argument(s)"
• 20: "Object not found"
• 99: "Undefined error" (please contact us if you keep getting this error message)

Pricing information

Pricing and validation information for phone numbers.

  <?xml version="1.0" encoding="UTF-8"?>
  <pricing>
    <total_costs>0.0219</total_costs>
    <numbers>
      <number cost="0.0105" valid="true">11234567890</number>
      <number cost="0.0114" valid="true">19876543210</number>
      <number valid="false">0123456789</number>
      <number valid="false">8765432100</number>
    </numbers>
  </pricing>

Example Session

Assume you want to connect a call between two numbers in the United States: 1-123-4567890 and 1-987-6543210.

pricing

First we want to know how much the call will cost per minute. Therefore we invoke the pricing action, passing it the numbers we wish to connect. Note that there‘s no difference between src and dst numbers, or call and conference. We just send all numbers participating in the call using multiple number[] parameters:

  https://api.talkety.com/xml/v1/pricing?number[]=11234567890&number[]=19876543210

The API validates the numbers and returns XML pricing information:

  <?xml version="1.0" encoding="UTF-8"?>
  <pricing>
    <total_costs>0.0219</total_costs>
    <numbers>
      <number cost="0.0105" valid="true">11234567890</number>
      <number cost="0.0114" valid="true">19876543210</number>
    </numbers>
  </pricing>

connect

Now we actually connect the call:

  https://api.talkety.com/xml/v1/84f4097bb4955c6c58ba452ece41c075/call_connect?src=11234567890&dst=19876543210

The API connects the call and returns an XML status response:

  <?xml version="1.0" encoding="UTF-8"?>
  <success>
    <call_id>148</call_id>
  </success>

Make sure you remember the call_id attribute.

status

After a while, we want to update the call information …

  https://api.talkety.com/xml/v1/84f4097bb4955c6c58ba452ece41c075/call_status?call_id=148

… to have a look at the attributes we are interested in:

  <?xml version="1.0" encoding="UTF-8"?>
  <call>
    <id>148</id>
    ...
    <call_status>connected</call_status>
    <total_costs>0.07644</total_costs>
    ...
  </call>

disconnect

To disconnect the call use the corresponding action …

  https://api.talkety.com/xml/v1/84f4097bb4955c6c58ba452ece41c075/call_disconnect?call_id=148

… which returns:

  <?xml version="1.0" encoding="UTF-8"?>
  <success>
    <call_id>148</call_id>
  </success>