Die sipgate APIs im Überblick

Corinna
17.05.2016 26 5:35 min

Dieser Post ist schon etwas älter. Dieser Artikel in unserem Hilfe-Center ist aktueller.


Eine API ist eine Programmierschnittstelle, mit der man Sachen automatisieren kann. sipgate bietet insgesamt 3 1/2 solcher Schnittstellen an. Das ist eher viel und man kann schon ein bisschen durcheinanderkommen. Selbst bei uns im Haus herrscht manchmal Unklarheit darüber. Diesbezügliche Unterhaltungen laufen typischerweise so ab:

“Wir haben da eine Kundin, die hat Fragen zur API und zwar -”
“Welche API genau?”

Jetzt möchten wir Licht ins Dunkel bringen und alle APIs (Stand: Mai 2016) kurz vorstellen:

Wie so oft bei einer verwirrenden Komplexität, ist diese historisch gewachsen. Früher, vor gefühlt 100 Internetjahren, war die Welt noch in Ordnung. Fernseher hatten runde Ecken, Faxe waren durch die Leitung gepresstes Papier mit rechtssicherer Unterschrift und Tastentelefone innovativ. Nach dem Fall des Telekom-Monopols wurde plötzlich alles anders. Aufbruchstimmung lag in der Luft. Der Post-Hörnchen-Muff verflog langsam. ISDN war todgeweiht, die Abschaltung nur eine Frage der Zeit. 2004 ging sipgate als Erster in Deutschland mit einem ISDN-Ersatz-Produkt auf Basis von SIP, einem offenen Internetstandard für VoIP, an den Start. Das Produkt hieß sipgate basic und zeigte durch seine niedrigen Kosten und nomadischen Anwendungsmöglichkeiten das riesige Potential der neuen Technik.

Durch die Verwendung von offenen Internetprotokollen ermöglichten wir die freie Wahl von Endgeräten und Software und somit flexiblere Einsatzmöglichkeiten. Mit der Einführung unserer ersten API folgte 2005 der nächste logische Schritt.

XML-RPC-API (aka “sipgate API”)

Dass man zum Versenden eines Faxes ein Faxgerät braucht und für SMS ein Handy, erschien uns schon 2005 antiquiert. Wir wollten unseren Kunden mehr bieten und schufen dafür eine Programmierschnittstelle: die sipgate XML-RPC-API. Diese API meinen wir, wenn wir auf unseren Webseiten und im Hilfe-Center von “sipgate API” sprechen.

Mit einem einfachen XML-Protokoll als Basis ist sie ein Kind ihrer Zeit. Die Erfahrung, dass SOAP zu umfangreich und kompliziert ist, haben zum Glück andere für uns gemacht. JSON und REST waren noch unpopulär. XML-RPC war ein guter Mittelweg.

Der Aufbau ist einfach: Vom sipgate-System angebotene Funktionen lassen sich durch ein Kommando in XML-Form aufrufen. Eine Antwort mit Status-Code und eventuellen Ergebnisdaten gibt es als XML zurück.

Die Nummer 1 Funktionalität, die Kunden realisieren wollen, ist Click2Dial (Wahlhilfe, Click2Call, …, wie man es auch immer nennen will): Man klickt auf eine Telefonnummer und ruft diese automatisch, ohne mühsames Abtippen, an. Das geht. Hier haben wir auf englisch aufgeschrieben, wie: book.sipgate.io/content/click2call.html

Ebenfalls möglich sind u. a. die automatische Abfrage des Kontostands, Fax- und SMS-Versand, sowie der Abruf der Anrufhistorie.

Die API ist für jeden sipgate-Account kostenlos verfügbar, und eine vollständige Dokumentation aller Funktionen lässt sich hier finden.

Die REST-API ist tot

Die REST-API von 2009 verschweigen wir in unserer Hilfe komplett, weil sie keiner mehr benutzen sollte! Sie wird nicht gepflegt. Die Doku stimmt nicht und wir konnten unseren Kunden bei Problemen schon lange nicht mehr wirklich helfen.

Daher stampfen wir die alte REST-API zum 1.7.2016 ein. Habt ihr Anmerkungen dazu? Vielleicht können wir euch die Umstellung erleichtern. Wendet euch an stefan@sipgate.io.

Lang lebe die REST-API!

Die Idee der REST-API war gut, nur unsere damalige Umsetzung war nicht überzeugend. Aber inzwischen sind 7 Jahre ins Land gegangen, in denen wir sehr, sehr viel gelernt haben. Deshalb entsteht in diesen Monaten die neue REST-API. Der große Unterschied zur alten besteht vor allem darin, dass wir die neue auch selbst zur Umsetzung unserer neuen Website verwenden. Wir sind überzeugt, dass dadurch eine tolle Developer-Experience entsteht. Eat your own dog food ;-) Die Anzahl der angebotenen Funktionen ist noch sehr übersichtlich, wächst aber stetig. Ein regelmäßiger Blick auf unsere Dokumentation (api.sipgate.com/doc/) lohnt sich. Trotz des frühen Entwicklungsstadiums laden wir jeden herzlich ein, damit zu entwickeln. Diese API ist kostenlos und für sipgate team, sipgate basic und simquadrat verfügbar.

sipgate.io – Push-API

Seit einem guten Jahr bietet sipgate die Möglichkeit, per Skript Einfluss auf ein- und ausgehende Gespräche zu nehmen. Und das in Echtzeit. Wir realisieren dies über eine an Webhooks angelehnte Push-API. Als Nutzer hinterlegt man dazu in unserem System eine URL, die wir bei Telefongesprächen aufrufen, um über den Anruf zu informieren und eventuell Steuerungsanweisungen zu bekommen. Anrufe umleiten oder Interaktion per DTMF-Tastenabfrage sind prominente Beispiele der angebotenen Funktionen.

Von den unzähligen Anwendungsmöglichkeiten scheinen das Erstellen von Anrufstatistiken und die Integration in CRM-Systeme am bedeutsamsten zu sein. Das zeigt unser bisheriges Kundenfeedback.

Demnach ist eine tiefe, aber einfache Integration in vorhandene Software um einiges gefragter, als eine offene Programmierschnittstelle. Das hat uns überrascht und dazu bewegt, unseren Fokus auf konkrete technische Partnerschaften zu verlagern. Die erste Kooperation – mit Zoho CRM – steht bereits: sipgateteam.de/zoho-crm

sipgate.io als Push-API bleibt weiterhin generisch, um vielfältige Anwendungsszenarien abzubilden. Heimautomatisierer, Privatspezialisten und Experimentierfreudige sind weiterhin herzlich eingeladen, mit dieser API zu entwickeln. Wir hoffen, den Einstieg so einfach wie möglich gestaltet zu haben. Die Dokumentation ist öffentlich auf sipgate.io. Unser Einstiegstarif ist kostenlos, und Supportanfragen beantworten wir, das Entwicklerteam, direkt.

Hier nochmal das Wichtigste zu allen APIs:

XML-RPC API

  • Funktionsumfang: Faxe versenden, SMS versenden, Anruf auslösen, Kontostand abfragen, Anrufhistorie abrufen, und vieles mehr
  • Für diese Produkte: sipgate team, sipgate basic, simquadrat und eingeschränkt für sipgate trunking
  • Preis: kostenlos
  • Dokumentation: XML-RPC API
  • Technologie: XML-RPC

Neue REST-API

  • Funktionsumfang: Endgeräteeinstellungen abfragen, Anruf auslösen, Weiterleitungen konfigurieren und vieles mehr
  • Für diese Produkte: sipgate team, sipgate basic und simquadrat
  • Preis: kostenlos
  • Dokumentation: api.sipgate.com/doc/
  • Technologie: REST, OAuth2

sipgate.io Push-API

  • Funktionsumfang: Echtzeit-Informationen über Anrufe und Anrufannahme an einen Webserver schicken; Anrufe automatisiert weiterleiten, auflegen oder auf Voicemail schicken; DTMF; und vieles mehr
  • Welche Produkte: sipgate team, sipgate basic und simquadrat
  • Preis: sipgate.io/de/prices
  • Dokumentation: sipgate.io (github)
  • Technologie: WebHooks
  • Für diese Produkte: sipgate team, sipgate basic und simquadrat

Haben wir was vergessen? Dann überhäuft uns mit Kommentaren! Wir freuen uns auf eure Fragen!

26 Kommentare


Markus Flögel:

Gibt es Neuigkeiten zu dem CSV-Import?

antworten

Markus Flögel:

Hallo,

ich habe einen Fehler in der Methode GetAllContacts in der RestApi gefunden. Diese liefert JSON-Objekte im falschen Format zurück.
Laut Schnittellenbeschreibung ist der Typ einer Nummer als ENUM definiert. Es wird jedoch ein Array mit Strings zurückgegeben.

Schnittstellenbeschreibung:

ContactsResponse {
items (Array[ContactResponse], optional)
}
ContactResponse {
id (string, optional),
name (string, optional),
picture (string, optional),
emails (Array[EMailResponse], optional),
numbers (Array[NumberResponse], optional),
addresses (Array[AddressResponse], optional),
organization (Array[Inline Model 1], optional)
}
EMailResponse {
email (string, optional),
type (Array[string], optional)
}
NumberResponse {
id (string, optional),
number (string, optional),
localized (string, optional),
type (string, optional) = [‚MOBILE‘, ‚LANDLINE‘, ‚QUICKDIAL‘, ‚INTERNATIONAL‘]
}

Rückgabe:
{
„items“: [
{
„id“: „9sdfsdfsd-e6fd-sdfsdb2b3-80f7fsdfsdf7245“,
„name“: „XXXXX“,
„picture“: null,
„emails“: [],
„numbers“: [
{
„number“: „9999999999“,
„type“: [
„home“
]
}
],
„addresses“: [],
„organization“: []
},

antworten

Laurent Emmanuel:

It would be nice if you can give some production environment api examples..

antworten

Daniel:

Ich habe ein paar Ideen und würde gerne etwas mit der REST-API bauen. Lässt sich darauf auf alle Einstellungen von sipgate team zugreifen oder nur auf bestimmte? Z.B. würde ich gerne als Erstes den Kompatibilitätsmodus ein- und ausschalten. Dann kann ich was bauen, was mir diesen nur für Gespräche aktiviert, die zu einem HD-fähigen Teilnehmer führen und sonst bleibt er aus, damit BLF, sipgate.io etc. funktionieren.

antworten

Norbert:

Hallo, ich versuche gerade auf ein Monitoring System mit automagisierten SMS-Versand zu bestücken und stecke gerade im kleinen Problem fest. Der zu verwendende sipgate Account ist von der Sorte sipgate Trunking. und ich hatte vor die sipgateAPI zu verwenden. Jetzt steht hier dass „sipgate Trunking“ von dieser API nur eingeschränkt unterstützt wird. Gibt es dennoch eine simple Methodik Web-SMS Versand über sipgate zu ermöglichen? Muss ich eventuell auf eine andere API zurückgreifen? (ICh verfüge bereits über fertige Routinen die auf ein sipgate Team Account abgefeuert das korrekte Ergebnis liefern. Soll heißen, mein Handy kann vibrieren ;D )

antworten

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.