docs (Voice): Add 'handle incoming call' tutorial

examples/compile.sh

@@ -1,3 +1,4 @@
 #!/bin/sh
 
 (cd tutorials/sms/auto-subscribe-app && mvn clean package)
+(cd tutorials/voice/handle-incoming-call && mvn clean package)

examples/tutorials/voice/handle-incoming-call/README.md

@@ -0,0 +1,79 @@
+# Handle Incoming Call webhook application sample
+
+This directory contains sample related to Java SDK tutorial: [Handle incoming call](https://developers.sinch.com/docs/voice/getting-started/java/incoming-call)
+
+## Requirements
+
+- JDK 21 or later
+- [Maven](https://maven.apache.org/)
+- [ngrok](https://ngrok.com/docs)
+- [Sinch account](https://dashboard.sinch.com)
+- Having a [Sinch phone number attached to your account](https://developers.sinch.com/docs/voice/getting-started/#3-assign-your-number)
+
+## Usage
+
+### Configure application settings
+
+Application settings is using the SpringBoot configuration file: [`application.yaml`](src/main/resources/application.yaml) file and set:
+
+#### Sinch credentials
+Located in `credentials.application` section (*you can find Voice application credentials you need on your [Sinch dashboard](https://dashboard.sinch.com/voice/apps)*):
+- `id`: YOUR_Voice_Application_Id
+- `secret`: YOUR_Voice_Application_Secret
+
+#### Webhook controller path
+Located in `voice` section you can modify: 
+- `controller-path`: path the server will respond to. <em>Default: /voice</em>
+
+#### Server port
+Located in `server` section:
+- port: The port to be used for listening for incoming requests. <em>Default: 8090</em>
+
+### Starting server locally
+
+Compile and run the application as server on your localhost.
+```bash
+mvn spring-boot:run
+```
+
+### Use ngrok to forward request to local server
+
+Forwarding request to same `8090` port used above:
+
+*Note: The `8090` value is coming from default config and can be changed (see [Server port](#Server port) configuration section)*
+
+```bash
+ngrok http 8090
+```
+
+ngrok output will contain output like the following:
+```
+ngrok                                                                                                                                                                                                                          (Ctrl+C to quit)
+
+...
+Forwarding                    https://0e64-78-117-86-140.ngrok-free.app -> http://localhost:8090
+
+```
+The line
+```
+Forwarding                    https://0e64-78-117-86-140.ngrok-free.app -> http://localhost:8090
+```
+Contains `https://0e64-78-117-86-140.ngrok-free.app` value.
+
+## Configure Voice application callback
+
+You have now a local web server responding to `/voice` path and `ngrok` instance running providing a bridge from `https://0e64-78-117-86-140.ngrok-free.app` onto local webserver.
+
+Last step is now to configure your dashboard to set Voice application callback to point towards your local webserver.
+
+The callback to be called by sinch will be in form of: `<bridge host>`/`<web server controller path>`
+
+e.g. According to previous sample values: https://0e64-78-117-86-140.ngrok-free.app/voice
+
+1. Go to your Voice application configuration: [Sinch Voice Apps dashboard](https://dashboard.sinch.com/voice/apps/)
+2. Edit the application setting related to the Application ID set from config file (see [Sinch credentials](#configure-application-settings))
+3. Fill `Callback URL` field with *https://0e64-78-117-86-140.ngrok-free.app/voice*
+
+You can now place a call to Sinch number attached to your Voice app (see [documentation](https://developers.sinch.com/docs/voice/getting-started/#3-assign-your-number)
+
+When calling your Sinch number attached to application, the Sinch platform will trigger an `Incoming Call Event (ICE)` toward your server your response will be served to the callee.

examples/tutorials/voice/handle-incoming-call/pom.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-parent</artifactId>
+    <version>3.2.5</version>
+    <relativePath/> <!-- lookup parent from repository -->
+  </parent>
+
+  <groupId>com.sinch.sdk</groupId>
+  <artifactId>sinch-sdk-java-sample-webhooks-app</artifactId>
+  <version>0.0.1-SNAPSHOT</version>
+  <name>Sinch Java SDK Handle Incoming Call Sample Application</name>
+  <description>Demo Project</description>
+
+  <properties>
+    <sinch.sdk.java.version>[1.0.0,)</sinch.sdk.java.version>
+    <java.version>21</java.version>
+  </properties>
+
+  <dependencies>
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>org.springframework.boot</groupId>
+      <artifactId>spring-boot-starter-web</artifactId>
+    </dependency>
+
+    <dependency>
+      <groupId>com.sinch.sdk</groupId>
+      <artifactId>sinch-sdk-java</artifactId>
+      <version>${sinch.sdk.java.version}</version>
+    </dependency>
+
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-maven-plugin</artifactId>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>

examples/tutorials/voice/handle-incoming-call/src/main/java/com/mycompany/app/App.java

@@ -0,0 +1,12 @@
+package com.mycompany.app;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+@SpringBootApplication
+public class App {
+
+  public static void main(String[] args) {
+    SpringApplication.run(App.class, args);
+  }
+}

examples/tutorials/voice/handle-incoming-call/src/main/java/com/mycompany/app/Config.java

@@ -0,0 +1,37 @@
+package com.mycompany.app;
+
+import com.sinch.sdk.SinchClient;
+import com.sinch.sdk.domains.voice.VoiceService;
+import com.sinch.sdk.models.Configuration;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.annotation.Bean;
+
+@org.springframework.context.annotation.Configuration
+public class Config {
+
+  @Value("${credentials.application.key}")
+  String applicationKey;
+
+  @Value("${credentials.application.secret}")
+  String applicationSecret;
+
+  @Value("${voice.controller-path}")
+  private String controllerPath;
+
+  @Bean
+  public VoiceService voiceService() {
+
+    var configuration =
+        Configuration.builder()
+            .setApplicationKey(applicationKey)
+            .setApplicationSecret(applicationSecret)
+            .build();
+
+    return new SinchClient(configuration).voice();
+  }
+
+  @Bean
+  String controllerPath() {
+    return controllerPath;
+  }
+}

examples/tutorials/voice/handle-incoming-call/src/main/java/com/mycompany/app/WebhookController.java

@@ -0,0 +1,67 @@
+package com.mycompany.app;
+
+import com.sinch.sdk.domains.voice.VoiceService;
+import com.sinch.sdk.domains.voice.models.webhooks.IncomingCallEvent;
+import java.util.Map;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+@RestController
+public class WebhookController {
+
+  private final VoiceService voiceService;
+  private final WebhookService webhookService;
+  private final String controllerPath;
+
+  @Autowired
+  public WebhookController(
+      VoiceService voiceService, WebhookService webhookService, String controllerPath) {
+    this.voiceService = voiceService;
+    this.webhookService = webhookService;
+    this.controllerPath = controllerPath;
+  }
+
+  @PostMapping(
+      value = "#{controllerPath}",
+      consumes = MediaType.APPLICATION_JSON_VALUE,
+      produces = MediaType.APPLICATION_JSON_VALUE)
+  public String voiceEvent(@RequestHeader Map<String, String> headers, @RequestBody String body) {
+
+    // ensure valid authentication before handling request
+    var validAuth =
+        voiceService
+            .webhooks()
+            .validateAuthenticatedRequest(
+                // The HTTP verb this controller is managing
+                "POST",
+                // The URI this path is managing
+                controllerPath,
+                // request headers
+                headers,
+                // request payload body
+                body);
+
+    // token validation failed
+    if (!validAuth) {
+      throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+    }
+
+    // decode the payload request
+    var event = voiceService.webhooks().unserializeWebhooksEvent(body);
+
+    if (!(event instanceof IncomingCallEvent)) {
+      return "";
+    }
+
+    // let business layer process the request
+    var response = webhookService.answered((IncomingCallEvent) event);
+
+    return voiceService.webhooks().serializeWebhooksResponse(response);
+  }
+}

examples/tutorials/voice/handle-incoming-call/src/main/java/com/mycompany/app/WebhookService.java

@@ -0,0 +1,33 @@
+package com.mycompany.app;
+
+import com.sinch.sdk.domains.voice.models.svaml.ActionHangUp;
+import com.sinch.sdk.domains.voice.models.svaml.InstructionSay;
+import com.sinch.sdk.domains.voice.models.svaml.SVAMLControl;
+import com.sinch.sdk.domains.voice.models.webhooks.IncomingCallEvent;
+import java.util.Collections;
+import java.util.logging.Logger;
+import org.springframework.stereotype.Component;
+
+@Component
+public class WebhookService {
+
+  private static final Logger LOGGER = Logger.getLogger(WebhookService.class.getName());
+
+  public SVAMLControl answered(IncomingCallEvent event) {
+
+    LOGGER.info(
+        "Incoming call from '%s' received for '%s' :".formatted(event.getCli(), event.getTo()));
+
+    var hangupAction = ActionHangUp.builder().build();
+
+    var sayInstruction =
+        InstructionSay.builder()
+            .setText("Thank you for calling Sinch. This call will now end.")
+            .build();
+
+    return SVAMLControl.builder()
+        .setInstructions(Collections.singletonList(sayInstruction))
+        .setAction(hangupAction)
+        .build();
+  }
+}

examples/tutorials/voice/handle-incoming-call/src/main/resources/application.yaml

@@ -0,0 +1,16 @@
+# springboot related config file
+
+logging:
+  level:
+    com: INFO
+
+server:
+    port: 8090
+
+credentials:
+  application:
+      key:
+      secret: 
+
+voice:
+  controller-path: /voice